kernel-doc (9b031c86506cef9acae45e61339fcf9deaabb793) kernel-doc (2c12c8103d8f15790cf880f1545dafa36acb004a)
1#!/usr/bin/env perl
2# SPDX-License-Identifier: GPL-2.0
3
4use warnings;
5use strict;
6
7## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
8## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##

--- 67 unchanged lines hidden (view full) ---

76 reStructuredText format.
77 -export-file FILE Specify an additional FILE in which to look for
78 EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with
79 -export or -internal. May be specified multiple times.
80
81Other parameters:
82 -v Verbose output, more warnings and other information.
83 -h Print this help.
1#!/usr/bin/env perl
2# SPDX-License-Identifier: GPL-2.0
3
4use warnings;
5use strict;
6
7## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
8## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##

--- 67 unchanged lines hidden (view full) ---

76 reStructuredText format.
77 -export-file FILE Specify an additional FILE in which to look for
78 EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with
79 -export or -internal. May be specified multiple times.
80
81Other parameters:
82 -v Verbose output, more warnings and other information.
83 -h Print this help.
84 -Werror Treat warnings as errors.
84
85EOF
86 print $message;
87 exit 1;
88}
89
90#
91# format of comments.

--- 116 unchanged lines hidden (view full) ---

208my $warnings = 0;
209my $anon_struct_union = 0;
210
211# match expressions used to find embedded type information
212my $type_constant = '\b``([^\`]+)``\b';
213my $type_constant2 = '\%([-_\w]+)';
214my $type_func = '(\w+)\(\)';
215my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
85
86EOF
87 print $message;
88 exit 1;
89}
90
91#
92# format of comments.

--- 116 unchanged lines hidden (view full) ---

209my $warnings = 0;
210my $anon_struct_union = 0;
211
212# match expressions used to find embedded type information
213my $type_constant = '\b``([^\`]+)``\b';
214my $type_constant2 = '\%([-_\w]+)';
215my $type_func = '(\w+)\(\)';
216my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
217my $type_param_ref = '([\!]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
216my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params
218my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params
219my $type_fp_param2 = '\@(\w+->\S+)\(\)'; # Special RST handling for structs with func ptr params
217my $type_env = '(\$\w+)';
218my $type_enum = '\&(enum\s*([_\w]+))';
219my $type_struct = '\&(struct\s*([_\w]+))';
220my $type_typedef = '\&(typedef\s*([_\w]+))';
221my $type_union = '\&(union\s*([_\w]+))';
222my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
223my $type_fallback = '\&([_\w]+)';
224my $type_member_func = $type_member . '\(\)';

--- 6 unchanged lines hidden (view full) ---

231 [$type_constant, "\$1"],
232 [$type_constant2, "\$1"],
233 [$type_func, "\\\\fB\$1\\\\fP"],
234 [$type_enum, "\\\\fI\$1\\\\fP"],
235 [$type_struct, "\\\\fI\$1\\\\fP"],
236 [$type_typedef, "\\\\fI\$1\\\\fP"],
237 [$type_union, "\\\\fI\$1\\\\fP"],
238 [$type_param, "\\\\fI\$1\\\\fP"],
220my $type_env = '(\$\w+)';
221my $type_enum = '\&(enum\s*([_\w]+))';
222my $type_struct = '\&(struct\s*([_\w]+))';
223my $type_typedef = '\&(typedef\s*([_\w]+))';
224my $type_union = '\&(union\s*([_\w]+))';
225my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
226my $type_fallback = '\&([_\w]+)';
227my $type_member_func = $type_member . '\(\)';

--- 6 unchanged lines hidden (view full) ---

234 [$type_constant, "\$1"],
235 [$type_constant2, "\$1"],
236 [$type_func, "\\\\fB\$1\\\\fP"],
237 [$type_enum, "\\\\fI\$1\\\\fP"],
238 [$type_struct, "\\\\fI\$1\\\\fP"],
239 [$type_typedef, "\\\\fI\$1\\\\fP"],
240 [$type_union, "\\\\fI\$1\\\\fP"],
241 [$type_param, "\\\\fI\$1\\\\fP"],
242 [$type_param_ref, "\\\\fI\$1\$2\\\\fP"],
239 [$type_member, "\\\\fI\$1\$2\$3\\\\fP"],
240 [$type_fallback, "\\\\fI\$1\\\\fP"]
241 );
242my $blankline_man = "";
243
244# rst-mode
245my @highlights_rst = (
246 [$type_constant, "``\$1``"],
247 [$type_constant2, "``\$1``"],
248 # Note: need to escape () to avoid func matching later
249 [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"],
250 [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
251 [$type_fp_param, "**\$1\\\\(\\\\)**"],
243 [$type_member, "\\\\fI\$1\$2\$3\\\\fP"],
244 [$type_fallback, "\\\\fI\$1\\\\fP"]
245 );
246my $blankline_man = "";
247
248# rst-mode
249my @highlights_rst = (
250 [$type_constant, "``\$1``"],
251 [$type_constant2, "``\$1``"],
252 # Note: need to escape () to avoid func matching later
253 [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"],
254 [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
255 [$type_fp_param, "**\$1\\\\(\\\\)**"],
256 [$type_fp_param2, "**\$1\\\\(\\\\)**"],
252 [$type_func, "\$1()"],
253 [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],
254 [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],
255 [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"],
256 [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"],
257 # in rst this can refer to any type
258 [$type_fallback, "\\:c\\:type\\:`\$1`"],
257 [$type_func, "\$1()"],
258 [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],
259 [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],
260 [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"],
261 [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"],
262 # in rst this can refer to any type
263 [$type_fallback, "\\:c\\:type\\:`\$1`"],
259 [$type_param, "**\$1**"]
264 [$type_param_ref, "**\$1\$2**"]
260 );
261my $blankline_rst = "\n";
262
263# read arguments
264if ($#ARGV == -1) {
265 usage();
266}
267
268my $kernelversion;
269my $dohighlight = "";
270
271my $verbose = 0;
265 );
266my $blankline_rst = "\n";
267
268# read arguments
269if ($#ARGV == -1) {
270 usage();
271}
272
273my $kernelversion;
274my $dohighlight = "";
275
276my $verbose = 0;
277my $Werror = 0;
272my $output_mode = "rst";
273my $output_preformatted = 0;
274my $no_doc_sections = 0;
275my $enable_lineno = 0;
276my @highlights = @highlights_rst;
277my $blankline = $blankline_rst;
278my $modulename = "Kernel API";
279

--- 30 unchanged lines hidden (view full) ---

310my $declaration_start_line;
311my ($type, $declaration_name, $return_type);
312my ($newsection, $newcontents, $prototype, $brcount, %source_map);
313
314if (defined($ENV{'KBUILD_VERBOSE'})) {
315 $verbose = "$ENV{'KBUILD_VERBOSE'}";
316}
317
278my $output_mode = "rst";
279my $output_preformatted = 0;
280my $no_doc_sections = 0;
281my $enable_lineno = 0;
282my @highlights = @highlights_rst;
283my $blankline = $blankline_rst;
284my $modulename = "Kernel API";
285

--- 30 unchanged lines hidden (view full) ---

316my $declaration_start_line;
317my ($type, $declaration_name, $return_type);
318my ($newsection, $newcontents, $prototype, $brcount, %source_map);
319
320if (defined($ENV{'KBUILD_VERBOSE'})) {
321 $verbose = "$ENV{'KBUILD_VERBOSE'}";
322}
323
324if (defined($ENV{'KDOC_WERROR'})) {
325 $Werror = "$ENV{'KDOC_WERROR'}";
326}
327
328if (defined($ENV{'KCFLAGS'})) {
329 my $kcflags = "$ENV{'KCFLAGS'}";
330
331 if ($kcflags =~ /Werror/) {
332 $Werror = 1;
333 }
334}
335
318# Generated docbook code is inserted in a template at a point where
319# docbook v3.1 requires a non-zero sequence of RefEntry's; see:
336# Generated docbook code is inserted in a template at a point where
337# docbook v3.1 requires a non-zero sequence of RefEntry's; see:
320# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
338# https://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
321# We keep track of number of generated entries and generate a dummy
322# if needs be to ensure the expanded template can be postprocessed
323# into html.
324my $section_counter = 0;
325
326my $lineprefix="";
327
328# Parser states
329use constant {
339# We keep track of number of generated entries and generate a dummy
340# if needs be to ensure the expanded template can be postprocessed
341# into html.
342my $section_counter = 0;
343
344my $lineprefix="";
345
346# Parser states
347use constant {
330 STATE_NORMAL => 0, # normal code
331 STATE_NAME => 1, # looking for function name
332 STATE_BODY_MAYBE => 2, # body - or maybe more description
333 STATE_BODY => 3, # the body of the comment
334 STATE_PROTO => 4, # scanning prototype
335 STATE_DOCBLOCK => 5, # documentation block
336 STATE_INLINE => 6, # gathering documentation outside main block
348 STATE_NORMAL => 0, # normal code
349 STATE_NAME => 1, # looking for function name
350 STATE_BODY_MAYBE => 2, # body - or maybe more description
351 STATE_BODY => 3, # the body of the comment
352 STATE_BODY_WITH_BLANK_LINE => 4, # the body, which has a blank line
353 STATE_PROTO => 5, # scanning prototype
354 STATE_DOCBLOCK => 6, # documentation block
355 STATE_INLINE => 7, # gathering doc outside main block
337};
338my $state;
339my $in_doc_sect;
340my $leading_space;
341
342# Inline documentation state
343use constant {
344 STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE)

--- 78 unchanged lines hidden (view full) ---

423 } elsif ($cmd eq "internal") { # only non-exported symbols
424 $output_selection = OUTPUT_INTERNAL;
425 %function_table = ();
426 } elsif ($cmd eq "export-file") {
427 my $file = shift @ARGV;
428 push(@export_file_list, $file);
429 } elsif ($cmd eq "v") {
430 $verbose = 1;
356};
357my $state;
358my $in_doc_sect;
359my $leading_space;
360
361# Inline documentation state
362use constant {
363 STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE)

--- 78 unchanged lines hidden (view full) ---

442 } elsif ($cmd eq "internal") { # only non-exported symbols
443 $output_selection = OUTPUT_INTERNAL;
444 %function_table = ();
445 } elsif ($cmd eq "export-file") {
446 my $file = shift @ARGV;
447 push(@export_file_list, $file);
448 } elsif ($cmd eq "v") {
449 $verbose = 1;
450 } elsif ($cmd eq "Werror") {
451 $Werror = 1;
431 } elsif (($cmd eq "h") || ($cmd eq "help")) {
432 usage();
433 } elsif ($cmd eq 'no-doc-sections') {
434 $no_doc_sections = 1;
435 } elsif ($cmd eq 'enable-lineno') {
436 $enable_lineno = 1;
437 } elsif ($cmd eq 'show-not-found') {
438 $show_not_found = 1; # A no-op but don't fail

--- 634 unchanged lines hidden (view full) ---

1073 # strip comments:
1074 $members =~ s/\/\*.*?\*\///gos;
1075 # strip attributes
1076 $members =~ s/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)/ /gi;
1077 $members =~ s/\s*__aligned\s*\([^;]*\)/ /gos;
1078 $members =~ s/\s*__packed\s*/ /gos;
1079 $members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos;
1080 $members =~ s/\s*____cacheline_aligned_in_smp/ /gos;
452 } elsif (($cmd eq "h") || ($cmd eq "help")) {
453 usage();
454 } elsif ($cmd eq 'no-doc-sections') {
455 $no_doc_sections = 1;
456 } elsif ($cmd eq 'enable-lineno') {
457 $enable_lineno = 1;
458 } elsif ($cmd eq 'show-not-found') {
459 $show_not_found = 1; # A no-op but don't fail

--- 634 unchanged lines hidden (view full) ---

1094 # strip comments:
1095 $members =~ s/\/\*.*?\*\///gos;
1096 # strip attributes
1097 $members =~ s/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)/ /gi;
1098 $members =~ s/\s*__aligned\s*\([^;]*\)/ /gos;
1099 $members =~ s/\s*__packed\s*/ /gos;
1100 $members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos;
1101 $members =~ s/\s*____cacheline_aligned_in_smp/ /gos;
1102
1081 # replace DECLARE_BITMAP
1103 # replace DECLARE_BITMAP
1104 $members =~ s/__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)/DECLARE_BITMAP($1, __ETHTOOL_LINK_MODE_MASK_NBITS)/gos;
1082 $members =~ s/DECLARE_BITMAP\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
1083 # replace DECLARE_HASHTABLE
1084 $members =~ s/DECLARE_HASHTABLE\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
1085 # replace DECLARE_KFIFO
1086 $members =~ s/DECLARE_KFIFO\s*\(([^,)]+),\s*([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos;
1087 # replace DECLARE_KFIFO_PTR
1088 $members =~ s/DECLARE_KFIFO_PTR\s*\(([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos;
1089

--- 669 unchanged lines hidden (view full) ---

1759 elsif ($x =~ /([^\{]*)/) {
1760 $prototype .= $1;
1761 }
1762
1763 if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
1764 $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
1765 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1766 $prototype =~ s@^\s+@@gos; # strip leading spaces
1105 $members =~ s/DECLARE_BITMAP\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
1106 # replace DECLARE_HASHTABLE
1107 $members =~ s/DECLARE_HASHTABLE\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
1108 # replace DECLARE_KFIFO
1109 $members =~ s/DECLARE_KFIFO\s*\(([^,)]+),\s*([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos;
1110 # replace DECLARE_KFIFO_PTR
1111 $members =~ s/DECLARE_KFIFO_PTR\s*\(([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos;
1112

--- 669 unchanged lines hidden (view full) ---

1782 elsif ($x =~ /([^\{]*)/) {
1783 $prototype .= $1;
1784 }
1785
1786 if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
1787 $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
1788 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1789 $prototype =~ s@^\s+@@gos; # strip leading spaces
1790
1791 # Handle prototypes for function pointers like:
1792 # int (*pcs_config)(struct foo)
1793 $prototype =~ s@^(\S+\s+)\(\s*\*(\S+)\)@$1$2@gos;
1794
1767 if ($prototype =~ /SYSCALL_DEFINE/) {
1768 syscall_munge();
1769 }
1770 if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
1771 $prototype =~ /DEFINE_SINGLE_EVENT/)
1772 {
1773 tracepoint_munge($file);
1774 }

--- 173 unchanged lines hidden (view full) ---

1948 $section =~ s/\.\.\.$//;
1949
1950 if ($verbose) {
1951 print STDERR "${file}:$.: warning: Variable macro arguments should be documented without dots\n";
1952 ++$warnings;
1953 }
1954 }
1955
1795 if ($prototype =~ /SYSCALL_DEFINE/) {
1796 syscall_munge();
1797 }
1798 if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
1799 $prototype =~ /DEFINE_SINGLE_EVENT/)
1800 {
1801 tracepoint_munge($file);
1802 }

--- 173 unchanged lines hidden (view full) ---

1976 $section =~ s/\.\.\.$//;
1977
1978 if ($verbose) {
1979 print STDERR "${file}:$.: warning: Variable macro arguments should be documented without dots\n";
1980 ++$warnings;
1981 }
1982 }
1983
1984 if ($state == STATE_BODY_WITH_BLANK_LINE && /^\s*\*\s?\S/) {
1985 dump_section($file, $section, $contents);
1986 $section = $section_default;
1987 $contents = "";
1988 }
1989
1956 if (/$doc_sect/i) { # case insensitive for supported section names
1957 $newsection = $1;
1958 $newcontents = $2;
1959
1960 # map the supported section names to the canonical names
1961 if ($newsection =~ m/^description$/i) {
1962 $newsection = $section_default;
1963 } elsif ($newsection =~ m/^context$/i) {

--- 37 unchanged lines hidden (view full) ---

2001 print STDERR "${file}:$.: warning: suspicious ending line: $_";
2002 ++$warnings;
2003 }
2004
2005 $prototype = "";
2006 $state = STATE_PROTO;
2007 $brcount = 0;
2008 } elsif (/$doc_content/) {
1990 if (/$doc_sect/i) { # case insensitive for supported section names
1991 $newsection = $1;
1992 $newcontents = $2;
1993
1994 # map the supported section names to the canonical names
1995 if ($newsection =~ m/^description$/i) {
1996 $newsection = $section_default;
1997 } elsif ($newsection =~ m/^context$/i) {

--- 37 unchanged lines hidden (view full) ---

2035 print STDERR "${file}:$.: warning: suspicious ending line: $_";
2036 ++$warnings;
2037 }
2038
2039 $prototype = "";
2040 $state = STATE_PROTO;
2041 $brcount = 0;
2042 } elsif (/$doc_content/) {
2009 # miguel-style comment kludge, look for blank lines after
2010 # @parameter line to signify start of description
2011 if ($1 eq "") {
2043 if ($1 eq "") {
2012 if ($section =~ m/^@/ || $section eq $section_context) {
2044 if ($section eq $section_context) {
2013 dump_section($file, $section, $contents);
2014 $section = $section_default;
2015 $contents = "";
2016 $new_start_line = $.;
2045 dump_section($file, $section, $contents);
2046 $section = $section_default;
2047 $contents = "";
2048 $new_start_line = $.;
2049 $state = STATE_BODY;
2017 } else {
2050 } else {
2051 if ($section ne $section_default) {
2052 $state = STATE_BODY_WITH_BLANK_LINE;
2053 } else {
2054 $state = STATE_BODY;
2055 }
2018 $contents .= "\n";
2019 }
2056 $contents .= "\n";
2057 }
2020 $state = STATE_BODY;
2021 } elsif ($state == STATE_BODY_MAYBE) {
2022 # Continued declaration purpose
2023 chomp($declaration_purpose);
2024 $declaration_purpose .= " " . $1;
2025 $declaration_purpose =~ s/\s+/ /g;
2026 } else {
2027 my $cont = $1;
2028 if ($section =~ m/^@/ || $section eq $section_context) {

--- 135 unchanged lines hidden (view full) ---

2164 }
2165 # Replace tabs by spaces
2166 while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
2167 # Hand this line to the appropriate state handler
2168 if ($state == STATE_NORMAL) {
2169 process_normal();
2170 } elsif ($state == STATE_NAME) {
2171 process_name($file, $_);
2058 } elsif ($state == STATE_BODY_MAYBE) {
2059 # Continued declaration purpose
2060 chomp($declaration_purpose);
2061 $declaration_purpose .= " " . $1;
2062 $declaration_purpose =~ s/\s+/ /g;
2063 } else {
2064 my $cont = $1;
2065 if ($section =~ m/^@/ || $section eq $section_context) {

--- 135 unchanged lines hidden (view full) ---

2201 }
2202 # Replace tabs by spaces
2203 while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
2204 # Hand this line to the appropriate state handler
2205 if ($state == STATE_NORMAL) {
2206 process_normal();
2207 } elsif ($state == STATE_NAME) {
2208 process_name($file, $_);
2172 } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE) {
2209 } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE ||
2210 $state == STATE_BODY_WITH_BLANK_LINE) {
2173 process_body($file, $_);
2174 } elsif ($state == STATE_INLINE) { # scanning for inline parameters
2175 process_inline($file, $_);
2176 } elsif ($state == STATE_PROTO) {
2177 process_proto($file, $_);
2178 } elsif ($state == STATE_DOCBLOCK) {
2179 process_docblock($file, $_);
2180 }

--- 54 unchanged lines hidden (view full) ---

2235}
2236if ($verbose && $errors) {
2237 print STDERR "$errors errors\n";
2238}
2239if ($verbose && $warnings) {
2240 print STDERR "$warnings warnings\n";
2241}
2242
2211 process_body($file, $_);
2212 } elsif ($state == STATE_INLINE) { # scanning for inline parameters
2213 process_inline($file, $_);
2214 } elsif ($state == STATE_PROTO) {
2215 process_proto($file, $_);
2216 } elsif ($state == STATE_DOCBLOCK) {
2217 process_docblock($file, $_);
2218 }

--- 54 unchanged lines hidden (view full) ---

2273}
2274if ($verbose && $errors) {
2275 print STDERR "$errors errors\n";
2276}
2277if ($verbose && $warnings) {
2278 print STDERR "$warnings warnings\n";
2279}
2280
2243exit($output_mode eq "none" ? 0 : $errors);
2281if ($Werror && $warnings) {
2282 print STDERR "$warnings warnings as Errors\n";
2283 exit($warnings);
2284} else {
2285 exit($output_mode eq "none" ? 0 : $errors)
2286}