1 #!/usr/bin/env perl 1 #!/usr/bin/env perl
2 # SPDX-License-Identifier: GPL-2.0 2 # SPDX-License-Identifier: GPL-2.0
3 # vim: softtabstop=4 <<
4 3
5 use warnings; 4 use warnings;
6 use strict; 5 use strict;
7 6
8 ## Copyright (c) 1998 Michael Zucchi, All Righ 7 ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
9 ## Copyright (C) 2000, 1 Tim Waugh <twaugh@red 8 ## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
10 ## Copyright (C) 2001 Simon Huggins 9 ## Copyright (C) 2001 Simon Huggins ##
11 ## Copyright (C) 2005-2012 Randy Dunlap 10 ## Copyright (C) 2005-2012 Randy Dunlap ##
12 ## Copyright (C) 2012 Dan Luedtke 11 ## Copyright (C) 2012 Dan Luedtke ##
13 ## 12 ## ##
14 ## #define enhancements by Armin Kuster <akuste 13 ## #define enhancements by Armin Kuster <akuster@mvista.com> ##
15 ## Copyright (c) 2000 MontaVista Software, Inc 14 ## Copyright (c) 2000 MontaVista Software, Inc. ##
16 # !! 15 ## ##
17 # Copyright (C) 2022 Tomasz Warniełło (POD) !! 16 ## This software falls under the GNU General Public License. ##
18 !! 17 ## Please read the COPYING file for more information ##
19 use Pod::Usage qw/pod2usage/; <<
20 <<
21 =head1 NAME <<
22 <<
23 kernel-doc - Print formatted kernel documentat <<
24 <<
25 =head1 SYNOPSIS <<
26 <<
27 kernel-doc [-h] [-v] [-Werror] [-Wall] [-Wret <<
28 [ -man | <<
29 -rst [-sphinx-version VERSION] [-enable-l <<
30 -none <<
31 ] <<
32 [ <<
33 -export | <<
34 -internal | <<
35 [-function NAME] ... | <<
36 [-nosymbol NAME] ... <<
37 ] <<
38 [-no-doc-sections] <<
39 [-export-file FILE] ... <<
40 FILE ... <<
41 <<
42 Run `kernel-doc -h` for details. <<
43 18
44 =head1 DESCRIPTION !! 19 # 18/01/2001 - Cleanups
>> 20 # Functions prototyped as foo(void) same as foo()
>> 21 # Stop eval'ing where we don't need to.
>> 22 # -- huggie@earth.li
>> 23
>> 24 # 27/06/2001 - Allowed whitespace after initial "/**" and
>> 25 # allowed comments before function declarations.
>> 26 # -- Christian Kreibich <ck@whoop.org>
>> 27
>> 28 # Still to do:
>> 29 # - add perldoc documentation
>> 30 # - Look more closely at some of the scarier bits :)
>> 31
>> 32 # 26/05/2001 - Support for separate source and object trees.
>> 33 # Return error code.
>> 34 # Keith Owens <kaos@ocs.com.au>
>> 35
>> 36 # 23/09/2001 - Added support for typedefs, structs, enums and unions
>> 37 # Support for Context section; can be terminated using empty line
>> 38 # Small fixes (like spaces vs. \s in regex)
>> 39 # -- Tim Jansen <tim@tjansen.de>
>> 40
>> 41 # 25/07/2012 - Added support for HTML5
>> 42 # -- Dan Luedtke <mail@danrl.de>
>> 43
>> 44 sub usage {
>> 45 my $message = <<"EOF";
>> 46 Usage: $0 [OPTION ...] FILE ...
45 47
46 Read C language source or header FILEs, extrac 48 Read C language source or header FILEs, extract embedded documentation comments,
47 and print formatted documentation to standard 49 and print formatted documentation to standard output.
48 50
49 The documentation comments are identified by t !! 51 The documentation comments are identified by "/**" opening comment mark. See
50 !! 52 Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
51 See Documentation/doc-guide/kernel-doc.rst for <<
52 <<
53 =cut <<
54 53
55 # more perldoc at the end of the file !! 54 Output format selection (mutually exclusive):
>> 55 -man Output troff manual page format. This is the default.
>> 56 -rst Output reStructuredText format.
>> 57 -none Do not output documentation, only warnings.
>> 58
>> 59 Output selection (mutually exclusive):
>> 60 -export Only output documentation for symbols that have been
>> 61 exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
>> 62 in any input FILE or -export-file FILE.
>> 63 -internal Only output documentation for symbols that have NOT been
>> 64 exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
>> 65 in any input FILE or -export-file FILE.
>> 66 -function NAME Only output documentation for the given function(s)
>> 67 or DOC: section title(s). All other functions and DOC:
>> 68 sections are ignored. May be specified multiple times.
>> 69 -nofunction NAME Do NOT output documentation for the given function(s);
>> 70 only output documentation for the other functions and
>> 71 DOC: sections. May be specified multiple times.
>> 72
>> 73 Output selection modifiers:
>> 74 -no-doc-sections Do not output DOC: sections.
>> 75 -enable-lineno Enable output of #define LINENO lines. Only works with
>> 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
>> 81 Other parameters:
>> 82 -v Verbose output, more warnings and other information.
>> 83 -h Print this help.
>> 84
>> 85 EOF
>> 86 print $message;
>> 87 exit 1;
>> 88 }
>> 89
>> 90 #
>> 91 # format of comments.
>> 92 # In the following table, (...)? signifies optional structure.
>> 93 # (...)* signifies 0 or more structure elements
>> 94 # /**
>> 95 # * function_name(:)? (- short description)?
>> 96 # (* @parameterx: (description of parameter x)?)*
>> 97 # (* a blank line)?
>> 98 # * (Description:)? (Description of function)?
>> 99 # * (section header: (section description)? )*
>> 100 # (*)?*/
>> 101 #
>> 102 # So .. the trivial example would be:
>> 103 #
>> 104 # /**
>> 105 # * my_function
>> 106 # */
>> 107 #
>> 108 # If the Description: header tag is omitted, then there must be a blank line
>> 109 # after the last parameter specification.
>> 110 # e.g.
>> 111 # /**
>> 112 # * my_function - does my stuff
>> 113 # * @my_arg: its mine damnit
>> 114 # *
>> 115 # * Does my stuff explained.
>> 116 # */
>> 117 #
>> 118 # or, could also use:
>> 119 # /**
>> 120 # * my_function - does my stuff
>> 121 # * @my_arg: its mine damnit
>> 122 # * Description: Does my stuff explained.
>> 123 # */
>> 124 # etc.
>> 125 #
>> 126 # Besides functions you can also write documentation for structs, unions,
>> 127 # enums and typedefs. Instead of the function name you must write the name
>> 128 # of the declaration; the struct/union/enum/typedef must always precede
>> 129 # the name. Nesting of declarations is not supported.
>> 130 # Use the argument mechanism to document members or constants.
>> 131 # e.g.
>> 132 # /**
>> 133 # * struct my_struct - short description
>> 134 # * @a: first member
>> 135 # * @b: second member
>> 136 # *
>> 137 # * Longer description
>> 138 # */
>> 139 # struct my_struct {
>> 140 # int a;
>> 141 # int b;
>> 142 # /* private: */
>> 143 # int c;
>> 144 # };
>> 145 #
>> 146 # All descriptions can be multiline, except the short function description.
>> 147 #
>> 148 # For really longs structs, you can also describe arguments inside the
>> 149 # body of the struct.
>> 150 # eg.
>> 151 # /**
>> 152 # * struct my_struct - short description
>> 153 # * @a: first member
>> 154 # * @b: second member
>> 155 # *
>> 156 # * Longer description
>> 157 # */
>> 158 # struct my_struct {
>> 159 # int a;
>> 160 # int b;
>> 161 # /**
>> 162 # * @c: This is longer description of C
>> 163 # *
>> 164 # * You can use paragraphs to describe arguments
>> 165 # * using this method.
>> 166 # */
>> 167 # int c;
>> 168 # };
>> 169 #
>> 170 # This should be use only for struct/enum members.
>> 171 #
>> 172 # You can also add additional sections. When documenting kernel functions you
>> 173 # should document the "Context:" of the function, e.g. whether the functions
>> 174 # can be called form interrupts. Unlike other sections you can end it with an
>> 175 # empty line.
>> 176 # A non-void function should have a "Return:" section describing the return
>> 177 # value(s).
>> 178 # Example-sections should contain the string EXAMPLE so that they are marked
>> 179 # appropriately in DocBook.
>> 180 #
>> 181 # Example:
>> 182 # /**
>> 183 # * user_function - function that can only be called in user context
>> 184 # * @a: some argument
>> 185 # * Context: !in_interrupt()
>> 186 # *
>> 187 # * Some description
>> 188 # * Example:
>> 189 # * user_function(22);
>> 190 # */
>> 191 # ...
>> 192 #
>> 193 #
>> 194 # All descriptive text is further processed, scanning for the following special
>> 195 # patterns, which are highlighted appropriately.
>> 196 #
>> 197 # 'funcname()' - function
>> 198 # '$ENVVAR' - environmental variable
>> 199 # '&struct_name' - name of a structure (up to two words including 'struct')
>> 200 # '&struct_name.member' - name of a structure member
>> 201 # '@parameter' - name of a parameter
>> 202 # '%CONST' - name of a constant.
>> 203 # '``LITERAL``' - literal string without any spaces on it.
56 204
57 ## init lots of data 205 ## init lots of data
58 206
59 my $errors = 0; 207 my $errors = 0;
60 my $warnings = 0; 208 my $warnings = 0;
61 my $anon_struct_union = 0; 209 my $anon_struct_union = 0;
62 210
63 # match expressions used to find embedded type 211 # match expressions used to find embedded type information
64 my $type_constant = '\b``([^\`]+)``\b'; 212 my $type_constant = '\b``([^\`]+)``\b';
65 my $type_constant2 = '\%([-_*\w]+)'; !! 213 my $type_constant2 = '\%([-_\w]+)';
66 my $type_func = '(\w+)\(\)'; 214 my $type_func = '(\w+)\(\)';
67 my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\ 215 my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
68 my $type_param_ref = '([\!~\*]?)\@(\w*((\.\w+) !! 216 my $type_param_ref = '([\!]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
69 my $type_fp_param = '\@(\w+)\(\)'; # Special 217 my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params
70 my $type_fp_param2 = '\@(\w+->\S+)\(\)'; # Sp 218 my $type_fp_param2 = '\@(\w+->\S+)\(\)'; # Special RST handling for structs with func ptr params
71 my $type_env = '(\$\w+)'; 219 my $type_env = '(\$\w+)';
72 my $type_enum = '\&(enum\s*([_\w]+))'; 220 my $type_enum = '\&(enum\s*([_\w]+))';
73 my $type_struct = '\&(struct\s*([_\w]+))'; 221 my $type_struct = '\&(struct\s*([_\w]+))';
74 my $type_typedef = '\&(typedef\s*([_\w]+))'; 222 my $type_typedef = '\&(typedef\s*([_\w]+))';
75 my $type_union = '\&(union\s*([_\w]+))'; 223 my $type_union = '\&(union\s*([_\w]+))';
76 my $type_member = '\&([_\w]+)(\.|->)([_\w]+)'; 224 my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
77 my $type_fallback = '\&([_\w]+)'; 225 my $type_fallback = '\&([_\w]+)';
78 my $type_member_func = $type_member . '\(\)'; 226 my $type_member_func = $type_member . '\(\)';
79 227
80 # Output conversion substitutions. 228 # Output conversion substitutions.
81 # One for each output format 229 # One for each output format
82 230
83 # these are pretty rough 231 # these are pretty rough
84 my @highlights_man = ( 232 my @highlights_man = (
85 [$type_constant, "\$1"], !! 233 [$type_constant, "\$1"],
86 [$type_constant2, "\$1"], !! 234 [$type_constant2, "\$1"],
87 [$type_func, "\\\\fB\$1\\\\fP"], !! 235 [$type_func, "\\\\fB\$1\\\\fP"],
88 [$type_enum, "\\\\fI\$1\\\\fP"], !! 236 [$type_enum, "\\\\fI\$1\\\\fP"],
89 [$type_struct, "\\\\fI\$1\\\\fP"], !! 237 [$type_struct, "\\\\fI\$1\\\\fP"],
90 [$type_typedef, "\\\\fI\$1\\\\fP"], !! 238 [$type_typedef, "\\\\fI\$1\\\\fP"],
91 [$type_union, "\\\\fI\$1\\\\fP"], !! 239 [$type_union, "\\\\fI\$1\\\\fP"],
92 [$type_param, "\\\\fI\$1\\\\fP"], !! 240 [$type_param, "\\\\fI\$1\\\\fP"],
93 [$type_param_ref, "\\\\fI\$1\$2\\\\fP"], !! 241 [$type_param_ref, "\\\\fI\$1\$2\\\\fP"],
94 [$type_member, "\\\\fI\$1\$2\$3\\\\fP"], !! 242 [$type_member, "\\\\fI\$1\$2\$3\\\\fP"],
95 [$type_fallback, "\\\\fI\$1\\\\fP"] !! 243 [$type_fallback, "\\\\fI\$1\\\\fP"]
96 ); !! 244 );
97 my $blankline_man = ""; 245 my $blankline_man = "";
98 246
99 # rst-mode 247 # rst-mode
100 my @highlights_rst = ( 248 my @highlights_rst = (
101 [$type_constant, "``\$1``"], !! 249 [$type_constant, "``\$1``"],
102 [$type_constant2, "``\$1``"], !! 250 [$type_constant2, "``\$1``"],
103 !! 251 # Note: need to escape () to avoid func matching later
104 # Note: need to escape () to avoid func ma !! 252 [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"],
105 [$type_member_func, "\\:c\\:type\\:`\$1\$2 !! 253 [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
106 [$type_member, "\\:c\\:type\\:`\$1\$2\$3 < !! 254 [$type_fp_param, "**\$1\\\\(\\\\)**"],
107 [$type_fp_param, "**\$1\\\\(\\\\)**"], !! 255 [$type_fp_param2, "**\$1\\\\(\\\\)**"],
108 [$type_fp_param2, "**\$1\\\\(\\\\)**"], !! 256 [$type_func, "\$1()"],
109 [$type_func, "\$1()"], !! 257 [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],
110 [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"], !! 258 [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],
111 [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`" !! 259 [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"],
112 [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>` !! 260 [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"],
113 [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"] !! 261 # in rst this can refer to any type
114 !! 262 [$type_fallback, "\\:c\\:type\\:`\$1`"],
115 # in rst this can refer to any type !! 263 [$type_param_ref, "**\$1\$2**"]
116 [$type_fallback, "\\:c\\:type\\:`\$1`"], !! 264 );
117 [$type_param_ref, "**\$1\$2**"] <<
118 ); <<
119 my $blankline_rst = "\n"; 265 my $blankline_rst = "\n";
120 266
121 # read arguments 267 # read arguments
122 if ($#ARGV == -1) { 268 if ($#ARGV == -1) {
123 pod2usage( !! 269 usage();
124 -message => "No arguments!\n", <<
125 -exitval => 1, <<
126 -verbose => 99, <<
127 -sections => 'SYNOPSIS', <<
128 -output => \*STDERR, <<
129 ); <<
130 } 270 }
131 271
132 my $kernelversion; 272 my $kernelversion;
133 my ($sphinx_major, $sphinx_minor, $sphinx_patc <<
134 <<
135 my $dohighlight = ""; 273 my $dohighlight = "";
136 274
137 my $verbose = 0; 275 my $verbose = 0;
138 my $Werror = 0; <<
139 my $Wreturn = 0; <<
140 my $Wshort_desc = 0; <<
141 my $Wcontents_before_sections = 0; <<
142 my $output_mode = "rst"; 276 my $output_mode = "rst";
143 my $output_preformatted = 0; 277 my $output_preformatted = 0;
144 my $no_doc_sections = 0; 278 my $no_doc_sections = 0;
145 my $enable_lineno = 0; 279 my $enable_lineno = 0;
146 my @highlights = @highlights_rst; 280 my @highlights = @highlights_rst;
147 my $blankline = $blankline_rst; 281 my $blankline = $blankline_rst;
148 my $modulename = "Kernel API"; 282 my $modulename = "Kernel API";
149 283
150 use constant { 284 use constant {
151 OUTPUT_ALL => 0, # output all sym 285 OUTPUT_ALL => 0, # output all symbols and doc sections
152 OUTPUT_INCLUDE => 1, # output only sp 286 OUTPUT_INCLUDE => 1, # output only specified symbols
153 OUTPUT_EXPORTED => 2, # output exporte !! 287 OUTPUT_EXCLUDE => 2, # output everything except specified symbols
154 OUTPUT_INTERNAL => 3, # output non-exp !! 288 OUTPUT_EXPORTED => 3, # output exported symbols
>> 289 OUTPUT_INTERNAL => 4, # output non-exported symbols
155 }; 290 };
156 my $output_selection = OUTPUT_ALL; 291 my $output_selection = OUTPUT_ALL;
157 my $show_not_found = 0; # No longer used 292 my $show_not_found = 0; # No longer used
158 293
159 my @export_file_list; 294 my @export_file_list;
160 295
161 my @build_time; 296 my @build_time;
162 if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) && 297 if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
163 (my $seconds = `date -d"${ENV{'KBUILD_BUIL 298 (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
164 @build_time = gmtime($seconds); 299 @build_time = gmtime($seconds);
165 } else { 300 } else {
166 @build_time = localtime; 301 @build_time = localtime;
167 } 302 }
168 303
169 my $man_date = ('January', 'February', 'March' 304 my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
170 'July', 'August', 'September', !! 305 'July', 'August', 'September', 'October',
171 'November', 'December')[$build !! 306 'November', 'December')[$build_time[4]] .
172 " " . ($build_time[5]+1900); !! 307 " " . ($build_time[5]+1900);
173 308
174 # Essentially these are globals. 309 # Essentially these are globals.
175 # They probably want to be tidied up, made mor 310 # They probably want to be tidied up, made more localised or something.
176 # CAVEAT EMPTOR! Some of the others I localis 311 # CAVEAT EMPTOR! Some of the others I localised may not want to be, which
177 # could cause "use of undefined value" or othe 312 # could cause "use of undefined value" or other bugs.
178 my ($function, %function_table, %parametertype 313 my ($function, %function_table, %parametertypes, $declaration_purpose);
179 my %nosymbol_table = (); <<
180 my $declaration_start_line; 314 my $declaration_start_line;
181 my ($type, $declaration_name, $return_type); 315 my ($type, $declaration_name, $return_type);
182 my ($newsection, $newcontents, $prototype, $br 316 my ($newsection, $newcontents, $prototype, $brcount, %source_map);
183 317
184 if (defined($ENV{'KBUILD_VERBOSE'}) && $ENV{'K !! 318 if (defined($ENV{'KBUILD_VERBOSE'})) {
185 $verbose = 1; !! 319 $verbose = "$ENV{'KBUILD_VERBOSE'}";
186 } 320 }
187 321
188 if (defined($ENV{'KCFLAGS'})) { <<
189 my $kcflags = "$ENV{'KCFLAGS'}"; <<
190 <<
191 if ($kcflags =~ /(\s|^)-Werror(\s|$)/) { <<
192 $Werror = 1; <<
193 } <<
194 } <<
195 <<
196 # reading this variable is for backwards compa <<
197 # someone was calling it with the variable fro <<
198 # kernel's build system <<
199 if (defined($ENV{'KDOC_WERROR'})) { <<
200 $Werror = "$ENV{'KDOC_WERROR'}"; <<
201 } <<
202 # other environment variables are converted to <<
203 # arguments in cmd_checkdoc in the build syste <<
204 <<
205 # Generated docbook code is inserted in a temp 322 # Generated docbook code is inserted in a template at a point where
206 # docbook v3.1 requires a non-zero sequence of 323 # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
207 # https://www.oasis-open.org/docbook/documenta 324 # https://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
208 # We keep track of number of generated entries 325 # We keep track of number of generated entries and generate a dummy
209 # if needs be to ensure the expanded template 326 # if needs be to ensure the expanded template can be postprocessed
210 # into html. 327 # into html.
211 my $section_counter = 0; 328 my $section_counter = 0;
212 329
213 my $lineprefix=""; 330 my $lineprefix="";
214 331
215 # Parser states 332 # Parser states
216 use constant { 333 use constant {
217 STATE_NORMAL => 0, # normal 334 STATE_NORMAL => 0, # normal code
218 STATE_NAME => 1, # looking 335 STATE_NAME => 1, # looking for function name
219 STATE_BODY_MAYBE => 2, # body - 336 STATE_BODY_MAYBE => 2, # body - or maybe more description
220 STATE_BODY => 3, # the bod 337 STATE_BODY => 3, # the body of the comment
221 STATE_BODY_WITH_BLANK_LINE => 4, # the bod 338 STATE_BODY_WITH_BLANK_LINE => 4, # the body, which has a blank line
222 STATE_PROTO => 5, # scannin 339 STATE_PROTO => 5, # scanning prototype
223 STATE_DOCBLOCK => 6, # documen 340 STATE_DOCBLOCK => 6, # documentation block
224 STATE_INLINE => 7, # gatheri 341 STATE_INLINE => 7, # gathering doc outside main block
225 }; 342 };
226 my $state; 343 my $state;
227 my $in_doc_sect; 344 my $in_doc_sect;
228 my $leading_space; 345 my $leading_space;
229 346
230 # Inline documentation state 347 # Inline documentation state
231 use constant { 348 use constant {
232 STATE_INLINE_NA => 0, # not applicable 349 STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE)
233 STATE_INLINE_NAME => 1, # looking for me 350 STATE_INLINE_NAME => 1, # looking for member name (@foo:)
234 STATE_INLINE_TEXT => 2, # looking for me 351 STATE_INLINE_TEXT => 2, # looking for member documentation
235 STATE_INLINE_END => 3, # done 352 STATE_INLINE_END => 3, # done
236 STATE_INLINE_ERROR => 4, # error - Commen 353 STATE_INLINE_ERROR => 4, # error - Comment without header was found.
237 # Spit a warning 354 # Spit a warning as it's not
238 # proper kernel- 355 # proper kernel-doc and ignore the rest.
239 }; 356 };
240 my $inline_doc_state; 357 my $inline_doc_state;
241 358
242 #declaration types: can be 359 #declaration types: can be
243 # 'function', 'struct', 'union', 'enum', 'type 360 # 'function', 'struct', 'union', 'enum', 'typedef'
244 my $decl_type; 361 my $decl_type;
245 362
246 # Name of the kernel-doc identifier for non-DO <<
247 my $identifier; <<
248 <<
249 my $doc_start = '^/\*\*\s*$'; # Allow whitespa 363 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
250 my $doc_end = '\*/'; 364 my $doc_end = '\*/';
251 my $doc_com = '\s*\*\s*'; 365 my $doc_com = '\s*\*\s*';
252 my $doc_com_body = '\s*\* ?'; 366 my $doc_com_body = '\s*\* ?';
253 my $doc_decl = $doc_com . '(\w+)'; 367 my $doc_decl = $doc_com . '(\w+)';
254 # @params and a strictly limited set of suppor 368 # @params and a strictly limited set of supported section names
255 # Specifically: <<
256 # Match @word: <<
257 # @...: <<
258 # @{section-name}: <<
259 # while trying to not match literal block star <<
260 # <<
261 my $doc_sect = $doc_com . 369 my $doc_sect = $doc_com .
262 '\s*(\@[.\w]+|\@\.\.\.|description|context !! 370 '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
263 my $doc_content = $doc_com_body . '(.*)'; 371 my $doc_content = $doc_com_body . '(.*)';
264 my $doc_block = $doc_com . 'DOC:\s*(.*)?'; 372 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
265 my $doc_inline_start = '^\s*/\*\*\s*$'; 373 my $doc_inline_start = '^\s*/\*\*\s*$';
266 my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.] 374 my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
267 my $doc_inline_end = '^\s*\*/\s*$'; 375 my $doc_inline_end = '^\s*\*/\s*$';
268 my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s] 376 my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
269 my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\ 377 my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
270 my $export_symbol_ns = '^\s*EXPORT_SYMBOL_NS(_ <<
271 my $function_pointer = qr{([^\(]*\(\*)\s*\)\s* <<
272 my $attribute = qr{__attribute__\s*\(\([a-z0-9 <<
273 378
274 my %parameterdescs; 379 my %parameterdescs;
275 my %parameterdesc_start_lines; 380 my %parameterdesc_start_lines;
276 my @parameterlist; 381 my @parameterlist;
277 my %sections; 382 my %sections;
278 my @sectionlist; 383 my @sectionlist;
279 my %section_start_lines; 384 my %section_start_lines;
280 my $sectcheck; 385 my $sectcheck;
281 my $struct_actual; 386 my $struct_actual;
282 387
283 my $contents = ""; 388 my $contents = "";
284 my $new_start_line = 0; 389 my $new_start_line = 0;
285 390
286 # the canonical section names. see also $doc_s 391 # the canonical section names. see also $doc_sect above.
287 my $section_default = "Description"; # defa 392 my $section_default = "Description"; # default section
288 my $section_intro = "Introduction"; 393 my $section_intro = "Introduction";
289 my $section = $section_default; 394 my $section = $section_default;
290 my $section_context = "Context"; 395 my $section_context = "Context";
291 my $section_return = "Return"; 396 my $section_return = "Return";
292 397
293 my $undescribed = "-- undescribed --"; 398 my $undescribed = "-- undescribed --";
294 399
295 reset_state(); 400 reset_state();
296 401
297 while ($ARGV[0] =~ m/^--?(.*)/) { 402 while ($ARGV[0] =~ m/^--?(.*)/) {
298 my $cmd = $1; 403 my $cmd = $1;
299 shift @ARGV; 404 shift @ARGV;
300 if ($cmd eq "man") { 405 if ($cmd eq "man") {
301 $output_mode = "man"; !! 406 $output_mode = "man";
302 @highlights = @highlights_man; !! 407 @highlights = @highlights_man;
303 $blankline = $blankline_man; !! 408 $blankline = $blankline_man;
304 } elsif ($cmd eq "rst") { 409 } elsif ($cmd eq "rst") {
305 $output_mode = "rst"; !! 410 $output_mode = "rst";
306 @highlights = @highlights_rst; !! 411 @highlights = @highlights_rst;
307 $blankline = $blankline_rst; !! 412 $blankline = $blankline_rst;
308 } elsif ($cmd eq "none") { 413 } elsif ($cmd eq "none") {
309 $output_mode = "none"; !! 414 $output_mode = "none";
310 } elsif ($cmd eq "module") { # not needed 415 } elsif ($cmd eq "module") { # not needed for XML, inherits from calling document
311 $modulename = shift @ARGV; !! 416 $modulename = shift @ARGV;
312 } elsif ($cmd eq "function") { # to only o 417 } elsif ($cmd eq "function") { # to only output specific functions
313 $output_selection = OUTPUT_INCLUDE; !! 418 $output_selection = OUTPUT_INCLUDE;
314 $function = shift @ARGV; !! 419 $function = shift @ARGV;
315 $function_table{$function} = 1; !! 420 $function_table{$function} = 1;
316 } elsif ($cmd eq "nosymbol") { # Exclude s !! 421 } elsif ($cmd eq "nofunction") { # output all except specific functions
317 my $symbol = shift @ARGV; !! 422 $output_selection = OUTPUT_EXCLUDE;
318 $nosymbol_table{$symbol} = 1; !! 423 $function = shift @ARGV;
>> 424 $function_table{$function} = 1;
319 } elsif ($cmd eq "export") { # only export 425 } elsif ($cmd eq "export") { # only exported symbols
320 $output_selection = OUTPUT_EXPORTED; !! 426 $output_selection = OUTPUT_EXPORTED;
321 %function_table = (); !! 427 %function_table = ();
322 } elsif ($cmd eq "internal") { # only non- 428 } elsif ($cmd eq "internal") { # only non-exported symbols
323 $output_selection = OUTPUT_INTERNAL; !! 429 $output_selection = OUTPUT_INTERNAL;
324 %function_table = (); !! 430 %function_table = ();
325 } elsif ($cmd eq "export-file") { 431 } elsif ($cmd eq "export-file") {
326 my $file = shift @ARGV; !! 432 my $file = shift @ARGV;
327 push(@export_file_list, $file); !! 433 push(@export_file_list, $file);
328 } elsif ($cmd eq "v") { 434 } elsif ($cmd eq "v") {
329 $verbose = 1; !! 435 $verbose = 1;
330 } elsif ($cmd eq "Werror") { <<
331 $Werror = 1; <<
332 } elsif ($cmd eq "Wreturn") { <<
333 $Wreturn = 1; <<
334 } elsif ($cmd eq "Wshort-desc" or $cmd eq <<
335 $Wshort_desc = 1; <<
336 } elsif ($cmd eq "Wcontents-before-section <<
337 $Wcontents_before_sections = 1; <<
338 } elsif ($cmd eq "Wall") { <<
339 $Wreturn = 1; <<
340 $Wshort_desc = 1; <<
341 $Wcontents_before_sections = 1; <<
342 } elsif (($cmd eq "h") || ($cmd eq "help") 436 } elsif (($cmd eq "h") || ($cmd eq "help")) {
343 pod2usage(-exitval => 0, -verbose => 2 !! 437 usage();
344 } elsif ($cmd eq 'no-doc-sections') { 438 } elsif ($cmd eq 'no-doc-sections') {
345 $no_doc_sections = 1; !! 439 $no_doc_sections = 1;
346 } elsif ($cmd eq 'enable-lineno') { 440 } elsif ($cmd eq 'enable-lineno') {
347 $enable_lineno = 1; !! 441 $enable_lineno = 1;
348 } elsif ($cmd eq 'show-not-found') { 442 } elsif ($cmd eq 'show-not-found') {
349 $show_not_found = 1; # A no-op but do !! 443 $show_not_found = 1; # A no-op but don't fail
350 } elsif ($cmd eq "sphinx-version") { <<
351 my $ver_string = shift @ARGV; <<
352 if ($ver_string =~ m/^(\d+)(\.\d+)?(\. <<
353 $sphinx_major = $1; <<
354 if (defined($2)) { <<
355 $sphinx_minor = substr($2,1); <<
356 } else { <<
357 $sphinx_minor = 0; <<
358 } <<
359 if (defined($3)) { <<
360 $sphinx_patch = substr($3,1) <<
361 } else { <<
362 $sphinx_patch = 0; <<
363 } <<
364 } else { <<
365 die "Sphinx version should either <<
366 } <<
367 } else { 444 } else {
368 # Unknown argument !! 445 # Unknown argument
369 pod2usage( !! 446 usage();
370 -message => "Argument unknown!\n", <<
371 -exitval => 1, <<
372 -verbose => 99, <<
373 -sections => 'SYNOPSIS', <<
374 -output => \*STDERR, <<
375 ); <<
376 } <<
377 if ($#ARGV < 0){ <<
378 pod2usage( <<
379 -message => "FILE argument missing <<
380 -exitval => 1, <<
381 -verbose => 99, <<
382 -sections => 'SYNOPSIS', <<
383 -output => \*STDERR, <<
384 ); <<
385 } 447 }
386 } 448 }
387 449
388 # continue execution near EOF; 450 # continue execution near EOF;
389 451
390 # The C domain dialect changed on Sphinx 3. So <<
391 # version in order to produce the right tags. <<
392 sub findprog($) <<
393 { <<
394 foreach(split(/:/, $ENV{PATH})) { <<
395 return "$_/$_[0]" if(-x "$_/$_[0]"); <<
396 } <<
397 } <<
398 <<
399 sub get_sphinx_version() <<
400 { <<
401 my $ver; <<
402 <<
403 my $cmd = "sphinx-build"; <<
404 if (!findprog($cmd)) { <<
405 my $cmd = "sphinx-build3"; <<
406 if (!findprog($cmd)) { <<
407 $sphinx_major = 1; <<
408 $sphinx_minor = 2; <<
409 $sphinx_patch = 0; <<
410 printf STDERR "Warning: Sphinx ver <<
411 $sphinx_major, $sphinx_mino <<
412 return; <<
413 } <<
414 } <<
415 <<
416 open IN, "$cmd --version 2>&1 |"; <<
417 while (<IN>) { <<
418 if (m/^\s*sphinx-build\s+([\d]+)\.([\d <<
419 $sphinx_major = $1; <<
420 $sphinx_minor = $2; <<
421 $sphinx_patch = $3; <<
422 last; <<
423 } <<
424 # Sphinx 1.2.x uses a different format <<
425 if (m/^\s*Sphinx.*\s+([\d]+)\.([\d\.]+ <<
426 $sphinx_major = $1; <<
427 $sphinx_minor = $2; <<
428 $sphinx_patch = $3; <<
429 last; <<
430 } <<
431 } <<
432 close IN; <<
433 } <<
434 <<
435 # get kernel version from env 452 # get kernel version from env
436 sub get_kernel_version() { 453 sub get_kernel_version() {
437 my $version = 'unknown kernel version'; 454 my $version = 'unknown kernel version';
438 455
439 if (defined($ENV{'KERNELVERSION'})) { 456 if (defined($ENV{'KERNELVERSION'})) {
440 $version = $ENV{'KERNELVERSION'}; !! 457 $version = $ENV{'KERNELVERSION'};
441 } 458 }
442 return $version; 459 return $version;
443 } 460 }
444 461
445 # 462 #
446 sub print_lineno { 463 sub print_lineno {
447 my $lineno = shift; 464 my $lineno = shift;
448 if ($enable_lineno && defined($lineno)) { 465 if ($enable_lineno && defined($lineno)) {
449 print ".. LINENO " . $lineno . "\n"; !! 466 print "#define LINENO " . $lineno . "\n";
450 } 467 }
451 } 468 }
452 <<
453 sub emit_warning { <<
454 my $location = shift; <<
455 my $msg = shift; <<
456 print STDERR "$location: warning: $msg"; <<
457 ++$warnings; <<
458 } <<
459 ## 469 ##
460 # dumps section contents to arrays/hashes inte 470 # dumps section contents to arrays/hashes intended for that purpose.
461 # 471 #
462 sub dump_section { 472 sub dump_section {
463 my $file = shift; 473 my $file = shift;
464 my $name = shift; 474 my $name = shift;
465 my $contents = join "\n", @_; 475 my $contents = join "\n", @_;
466 476
467 if ($name =~ m/$type_param/) { 477 if ($name =~ m/$type_param/) {
468 $name = $1; !! 478 $name = $1;
469 $parameterdescs{$name} = $contents; !! 479 $parameterdescs{$name} = $contents;
470 $sectcheck = $sectcheck . $name . " "; !! 480 $sectcheck = $sectcheck . $name . " ";
471 $parameterdesc_start_lines{$name} = $n 481 $parameterdesc_start_lines{$name} = $new_start_line;
472 $new_start_line = 0; 482 $new_start_line = 0;
473 } elsif ($name eq "@\.\.\.") { 483 } elsif ($name eq "@\.\.\.") {
474 $name = "..."; !! 484 $name = "...";
475 $parameterdescs{$name} = $contents; !! 485 $parameterdescs{$name} = $contents;
476 $sectcheck = $sectcheck . $name . " "; !! 486 $sectcheck = $sectcheck . $name . " ";
477 $parameterdesc_start_lines{$name} = $n 487 $parameterdesc_start_lines{$name} = $new_start_line;
478 $new_start_line = 0; 488 $new_start_line = 0;
479 } else { 489 } else {
480 if (defined($sections{$name}) && ($sec !! 490 if (defined($sections{$name}) && ($sections{$name} ne "")) {
481 # Only warn on user specified dupl !! 491 # Only warn on user specified duplicate section names.
482 if ($name ne $section_default) { !! 492 if ($name ne $section_default) {
483 emit_warning("${file}:$.", "du !! 493 print STDERR "${file}:$.: warning: duplicate section name '$name'\n";
484 } !! 494 ++$warnings;
485 $sections{$name} .= $contents; !! 495 }
486 } else { !! 496 $sections{$name} .= $contents;
487 $sections{$name} = $contents; !! 497 } else {
488 push @sectionlist, $name; !! 498 $sections{$name} = $contents;
>> 499 push @sectionlist, $name;
489 $section_start_lines{$name} = $new 500 $section_start_lines{$name} = $new_start_line;
490 $new_start_line = 0; 501 $new_start_line = 0;
491 } !! 502 }
492 } 503 }
493 } 504 }
494 505
495 ## 506 ##
496 # dump DOC: section after checking that it sho 507 # dump DOC: section after checking that it should go out
497 # 508 #
498 sub dump_doc_section { 509 sub dump_doc_section {
499 my $file = shift; 510 my $file = shift;
500 my $name = shift; 511 my $name = shift;
501 my $contents = join "\n", @_; 512 my $contents = join "\n", @_;
502 513
503 if ($no_doc_sections) { 514 if ($no_doc_sections) {
504 return; 515 return;
505 } 516 }
506 517
507 return if (defined($nosymbol_table{$name}) <<
508 <<
509 if (($output_selection == OUTPUT_ALL) || 518 if (($output_selection == OUTPUT_ALL) ||
510 (($output_selection == OUTPUT_INCLUDE) !! 519 ($output_selection == OUTPUT_INCLUDE &&
511 defined($function_table{$name}))) !! 520 defined($function_table{$name})) ||
>> 521 ($output_selection == OUTPUT_EXCLUDE &&
>> 522 !defined($function_table{$name})))
512 { 523 {
513 dump_section($file, $name, $contents); !! 524 dump_section($file, $name, $contents);
514 output_blockhead({'sectionlist' => \@s !! 525 output_blockhead({'sectionlist' => \@sectionlist,
515 'sections' => \%sect !! 526 'sections' => \%sections,
516 'module' => $modulen !! 527 'module' => $modulename,
517 'content-only' => ($ !! 528 'content-only' => ($output_selection != OUTPUT_ALL), });
518 } 529 }
519 } 530 }
520 531
521 ## 532 ##
522 # output function 533 # output function
523 # 534 #
524 # parameterdescs, a hash. 535 # parameterdescs, a hash.
525 # function => "function name" 536 # function => "function name"
526 # parameterlist => @list of parameters 537 # parameterlist => @list of parameters
527 # parameterdescs => %parameter descriptions 538 # parameterdescs => %parameter descriptions
528 # sectionlist => @list of sections 539 # sectionlist => @list of sections
529 # sections => %section descriptions 540 # sections => %section descriptions
530 # 541 #
531 542
532 sub output_highlight { 543 sub output_highlight {
533 my $contents = join "\n",@_; 544 my $contents = join "\n",@_;
534 my $line; 545 my $line;
535 546
536 # DEBUG 547 # DEBUG
537 # if (!defined $contents) { 548 # if (!defined $contents) {
538 # use Carp; 549 # use Carp;
539 # confess "output_highlight got called w 550 # confess "output_highlight got called with no args?\n";
540 # } 551 # }
541 552
542 # print STDERR "contents b4:$contents\n"; 553 # print STDERR "contents b4:$contents\n";
543 eval $dohighlight; 554 eval $dohighlight;
544 die $@ if $@; 555 die $@ if $@;
545 # print STDERR "contents af:$contents\n"; 556 # print STDERR "contents af:$contents\n";
546 557
547 foreach $line (split "\n", $contents) { 558 foreach $line (split "\n", $contents) {
548 if (! $output_preformatted) { !! 559 if (! $output_preformatted) {
549 $line =~ s/^\s*//; !! 560 $line =~ s/^\s*//;
550 } !! 561 }
551 if ($line eq ""){ !! 562 if ($line eq ""){
552 if (! $output_preformatted) { !! 563 if (! $output_preformatted) {
553 print $lineprefix, $blankline; !! 564 print $lineprefix, $blankline;
554 } !! 565 }
555 } else { !! 566 } else {
556 if ($output_mode eq "man" && subst !! 567 if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
557 print "\\&$line"; !! 568 print "\\&$line";
558 } else { !! 569 } else {
559 print $lineprefix, $line; !! 570 print $lineprefix, $line;
560 } !! 571 }
561 } !! 572 }
562 print "\n"; !! 573 print "\n";
563 } 574 }
564 } 575 }
565 576
566 ## 577 ##
567 # output function in man 578 # output function in man
568 sub output_function_man(%) { 579 sub output_function_man(%) {
569 my %args = %{$_[0]}; 580 my %args = %{$_[0]};
570 my ($parameter, $section); 581 my ($parameter, $section);
571 my $count; 582 my $count;
572 583
573 print ".TH \"$args{'function'}\" 9 \"$args 584 print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
574 585
575 print ".SH NAME\n"; 586 print ".SH NAME\n";
576 print $args{'function'} . " \\- " . $args{ 587 print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
577 588
578 print ".SH SYNOPSIS\n"; 589 print ".SH SYNOPSIS\n";
579 if ($args{'functiontype'} ne "") { 590 if ($args{'functiontype'} ne "") {
580 print ".B \"" . $args{'functiontype'} !! 591 print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
581 } else { 592 } else {
582 print ".B \"" . $args{'function'} . "\ !! 593 print ".B \"" . $args{'function'} . "\n";
583 } 594 }
584 $count = 0; 595 $count = 0;
585 my $parenth = "("; 596 my $parenth = "(";
586 my $post = ","; 597 my $post = ",";
587 foreach my $parameter (@{$args{'parameterl 598 foreach my $parameter (@{$args{'parameterlist'}}) {
588 if ($count == $#{$args{'parameterlist' !! 599 if ($count == $#{$args{'parameterlist'}}) {
589 $post = ");"; !! 600 $post = ");";
590 } !! 601 }
591 $type = $args{'parametertypes'}{$param !! 602 $type = $args{'parametertypes'}{$parameter};
592 if ($type =~ m/$function_pointer/) { !! 603 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
593 # pointer-to-function !! 604 # pointer-to-function
594 print ".BI \"" . $parenth . $1 . " !! 605 print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n";
595 } else { !! 606 } else {
596 $type =~ s/([^\*])$/$1 /; !! 607 $type =~ s/([^\*])$/$1 /;
597 print ".BI \"" . $parenth . $type !! 608 print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n";
598 } !! 609 }
599 $count++; !! 610 $count++;
600 $parenth = ""; !! 611 $parenth = "";
601 } 612 }
602 613
603 print ".SH ARGUMENTS\n"; 614 print ".SH ARGUMENTS\n";
604 foreach $parameter (@{$args{'parameterlist 615 foreach $parameter (@{$args{'parameterlist'}}) {
605 my $parameter_name = $parameter; !! 616 my $parameter_name = $parameter;
606 $parameter_name =~ s/\[.*//; !! 617 $parameter_name =~ s/\[.*//;
607 618
608 print ".IP \"" . $parameter . "\" 12\n !! 619 print ".IP \"" . $parameter . "\" 12\n";
609 output_highlight($args{'parameterdescs !! 620 output_highlight($args{'parameterdescs'}{$parameter_name});
610 } 621 }
611 foreach $section (@{$args{'sectionlist'}}) 622 foreach $section (@{$args{'sectionlist'}}) {
612 print ".SH \"", uc $section, "\"\n"; !! 623 print ".SH \"", uc $section, "\"\n";
613 output_highlight($args{'sections'}{$se !! 624 output_highlight($args{'sections'}{$section});
614 } 625 }
615 } 626 }
616 627
617 ## 628 ##
618 # output enum in man 629 # output enum in man
619 sub output_enum_man(%) { 630 sub output_enum_man(%) {
620 my %args = %{$_[0]}; 631 my %args = %{$_[0]};
621 my ($parameter, $section); 632 my ($parameter, $section);
622 my $count; 633 my $count;
623 634
624 print ".TH \"$args{'module'}\" 9 \"enum $a 635 print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
625 636
626 print ".SH NAME\n"; 637 print ".SH NAME\n";
627 print "enum " . $args{'enum'} . " \\- " . 638 print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
628 639
629 print ".SH SYNOPSIS\n"; 640 print ".SH SYNOPSIS\n";
630 print "enum " . $args{'enum'} . " {\n"; 641 print "enum " . $args{'enum'} . " {\n";
631 $count = 0; 642 $count = 0;
632 foreach my $parameter (@{$args{'parameterl 643 foreach my $parameter (@{$args{'parameterlist'}}) {
633 print ".br\n.BI \" $parameter\"\n"; !! 644 print ".br\n.BI \" $parameter\"\n";
634 if ($count == $#{$args{'parameterlist' !! 645 if ($count == $#{$args{'parameterlist'}}) {
635 print "\n};\n"; !! 646 print "\n};\n";
636 last; !! 647 last;
637 } else { !! 648 }
638 print ", \n.br\n"; !! 649 else {
639 } !! 650 print ", \n.br\n";
640 $count++; !! 651 }
>> 652 $count++;
641 } 653 }
642 654
643 print ".SH Constants\n"; 655 print ".SH Constants\n";
644 foreach $parameter (@{$args{'parameterlist 656 foreach $parameter (@{$args{'parameterlist'}}) {
645 my $parameter_name = $parameter; !! 657 my $parameter_name = $parameter;
646 $parameter_name =~ s/\[.*//; !! 658 $parameter_name =~ s/\[.*//;
647 659
648 print ".IP \"" . $parameter . "\" 12\n !! 660 print ".IP \"" . $parameter . "\" 12\n";
649 output_highlight($args{'parameterdescs !! 661 output_highlight($args{'parameterdescs'}{$parameter_name});
650 } 662 }
651 foreach $section (@{$args{'sectionlist'}}) 663 foreach $section (@{$args{'sectionlist'}}) {
652 print ".SH \"$section\"\n"; !! 664 print ".SH \"$section\"\n";
653 output_highlight($args{'sections'}{$se !! 665 output_highlight($args{'sections'}{$section});
654 } 666 }
655 } 667 }
656 668
657 ## 669 ##
658 # output struct in man 670 # output struct in man
659 sub output_struct_man(%) { 671 sub output_struct_man(%) {
660 my %args = %{$_[0]}; 672 my %args = %{$_[0]};
661 my ($parameter, $section); 673 my ($parameter, $section);
662 674
663 print ".TH \"$args{'module'}\" 9 \"" . $ar 675 print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";
664 676
665 print ".SH NAME\n"; 677 print ".SH NAME\n";
666 print $args{'type'} . " " . $args{'struct' 678 print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
667 679
668 my $declaration = $args{'definition'}; 680 my $declaration = $args{'definition'};
669 $declaration =~ s/\t/ /g; 681 $declaration =~ s/\t/ /g;
670 $declaration =~ s/\n/"\n.br\n.BI \"/g; 682 $declaration =~ s/\n/"\n.br\n.BI \"/g;
671 print ".SH SYNOPSIS\n"; 683 print ".SH SYNOPSIS\n";
672 print $args{'type'} . " " . $args{'struct' 684 print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
673 print ".BI \"$declaration\n};\n.br\n\n"; 685 print ".BI \"$declaration\n};\n.br\n\n";
674 686
675 print ".SH Members\n"; 687 print ".SH Members\n";
676 foreach $parameter (@{$args{'parameterlist 688 foreach $parameter (@{$args{'parameterlist'}}) {
677 ($parameter =~ /^#/) && next; !! 689 ($parameter =~ /^#/) && next;
678 690
679 my $parameter_name = $parameter; !! 691 my $parameter_name = $parameter;
680 $parameter_name =~ s/\[.*//; !! 692 $parameter_name =~ s/\[.*//;
681 693
682 ($args{'parameterdescs'}{$parameter_na !! 694 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
683 print ".IP \"" . $parameter . "\" 12\n !! 695 print ".IP \"" . $parameter . "\" 12\n";
684 output_highlight($args{'parameterdescs !! 696 output_highlight($args{'parameterdescs'}{$parameter_name});
685 } 697 }
686 foreach $section (@{$args{'sectionlist'}}) 698 foreach $section (@{$args{'sectionlist'}}) {
687 print ".SH \"$section\"\n"; !! 699 print ".SH \"$section\"\n";
688 output_highlight($args{'sections'}{$se !! 700 output_highlight($args{'sections'}{$section});
689 } 701 }
690 } 702 }
691 703
692 ## 704 ##
693 # output typedef in man 705 # output typedef in man
694 sub output_typedef_man(%) { 706 sub output_typedef_man(%) {
695 my %args = %{$_[0]}; 707 my %args = %{$_[0]};
696 my ($parameter, $section); 708 my ($parameter, $section);
697 709
698 print ".TH \"$args{'module'}\" 9 \"$args{' 710 print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
699 711
700 print ".SH NAME\n"; 712 print ".SH NAME\n";
701 print "typedef " . $args{'typedef'} . " \\ 713 print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
702 714
703 foreach $section (@{$args{'sectionlist'}}) 715 foreach $section (@{$args{'sectionlist'}}) {
704 print ".SH \"$section\"\n"; !! 716 print ".SH \"$section\"\n";
705 output_highlight($args{'sections'}{$se !! 717 output_highlight($args{'sections'}{$section});
706 } 718 }
707 } 719 }
708 720
709 sub output_blockhead_man(%) { 721 sub output_blockhead_man(%) {
710 my %args = %{$_[0]}; 722 my %args = %{$_[0]};
711 my ($parameter, $section); 723 my ($parameter, $section);
712 my $count; 724 my $count;
713 725
714 print ".TH \"$args{'module'}\" 9 \"$args{' 726 print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
715 727
716 foreach $section (@{$args{'sectionlist'}}) 728 foreach $section (@{$args{'sectionlist'}}) {
717 print ".SH \"$section\"\n"; !! 729 print ".SH \"$section\"\n";
718 output_highlight($args{'sections'}{$se !! 730 output_highlight($args{'sections'}{$section});
719 } 731 }
720 } 732 }
721 733
722 ## 734 ##
723 # output in restructured text 735 # output in restructured text
724 # 736 #
725 737
726 # 738 #
727 # This could use some work; it's used to outpu 739 # This could use some work; it's used to output the DOC: sections, and
728 # starts by putting out the name of the doc se 740 # starts by putting out the name of the doc section itself, but that tends
729 # to duplicate a header already in the templat 741 # to duplicate a header already in the template file.
730 # 742 #
731 sub output_blockhead_rst(%) { 743 sub output_blockhead_rst(%) {
732 my %args = %{$_[0]}; 744 my %args = %{$_[0]};
733 my ($parameter, $section); 745 my ($parameter, $section);
734 746
735 foreach $section (@{$args{'sectionlist'}}) 747 foreach $section (@{$args{'sectionlist'}}) {
736 next if (defined($nosymbol_table{$sect !! 748 if ($output_selection != OUTPUT_INCLUDE) {
737 !! 749 print "**$section**\n\n";
738 if ($output_selection != OUTPUT_INCLUD !! 750 }
739 print ".. _$section:\n\n"; <<
740 print "**$section**\n\n"; <<
741 } <<
742 print_lineno($section_start_lines{$sec 751 print_lineno($section_start_lines{$section});
743 output_highlight_rst($args{'sections'} !! 752 output_highlight_rst($args{'sections'}{$section});
744 print "\n"; !! 753 print "\n";
745 } 754 }
746 } 755 }
747 756
748 # 757 #
749 # Apply the RST highlights to a sub-block of t 758 # Apply the RST highlights to a sub-block of text.
750 # 759 #
751 sub highlight_block($) { 760 sub highlight_block($) {
752 # The dohighlight kludge requires the text 761 # The dohighlight kludge requires the text be called $contents
753 my $contents = shift; 762 my $contents = shift;
754 eval $dohighlight; 763 eval $dohighlight;
755 die $@ if $@; 764 die $@ if $@;
756 return $contents; 765 return $contents;
757 } 766 }
758 767
759 # 768 #
760 # Regexes used only here. 769 # Regexes used only here.
761 # 770 #
762 my $sphinx_literal = '^[^.].*::$'; 771 my $sphinx_literal = '^[^.].*::$';
763 my $sphinx_cblock = '^\.\.\ +code-block::'; 772 my $sphinx_cblock = '^\.\.\ +code-block::';
764 773
765 sub output_highlight_rst { 774 sub output_highlight_rst {
766 my $input = join "\n",@_; 775 my $input = join "\n",@_;
767 my $output = ""; 776 my $output = "";
768 my $line; 777 my $line;
769 my $in_literal = 0; 778 my $in_literal = 0;
770 my $litprefix; 779 my $litprefix;
771 my $block = ""; 780 my $block = "";
772 781
773 foreach $line (split "\n",$input) { 782 foreach $line (split "\n",$input) {
774 # !! 783 #
775 # If we're in a literal block, see if !! 784 # If we're in a literal block, see if we should drop out
776 # of it. Otherwise pass the line stra !! 785 # of it. Otherwise pass the line straight through unmunged.
777 # !! 786 #
778 if ($in_literal) { !! 787 if ($in_literal) {
779 if (! ($line =~ /^\s*$/)) { !! 788 if (! ($line =~ /^\s*$/)) {
780 # !! 789 #
781 # If this is the first non-bla !! 790 # If this is the first non-blank line in a literal
782 # block we need to figure out !! 791 # block we need to figure out what the proper indent is.
783 # !! 792 #
784 if ($litprefix eq "") { !! 793 if ($litprefix eq "") {
785 $line =~ /^(\s*)/; !! 794 $line =~ /^(\s*)/;
786 $litprefix = '^' . $1; !! 795 $litprefix = '^' . $1;
787 $output .= $line . "\n"; !! 796 $output .= $line . "\n";
788 } elsif (! ($line =~ /$litpref !! 797 } elsif (! ($line =~ /$litprefix/)) {
789 $in_literal = 0; !! 798 $in_literal = 0;
790 } else { !! 799 } else {
791 $output .= $line . "\n"; !! 800 $output .= $line . "\n";
792 } !! 801 }
793 } else { !! 802 } else {
794 $output .= $line . "\n"; !! 803 $output .= $line . "\n";
795 } !! 804 }
796 } !! 805 }
797 # !! 806 #
798 # Not in a literal block (or just drop !! 807 # Not in a literal block (or just dropped out)
799 # !! 808 #
800 if (! $in_literal) { !! 809 if (! $in_literal) {
801 $block .= $line . "\n"; !! 810 $block .= $line . "\n";
802 if (($line =~ /$sphinx_literal/) | !! 811 if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) {
803 $in_literal = 1; !! 812 $in_literal = 1;
804 $litprefix = ""; !! 813 $litprefix = "";
805 $output .= highlight_block($bl !! 814 $output .= highlight_block($block);
806 $block = "" !! 815 $block = ""
807 } !! 816 }
808 } !! 817 }
809 } 818 }
810 819
811 if ($block) { 820 if ($block) {
812 $output .= highlight_block($block); !! 821 $output .= highlight_block($block);
813 } 822 }
814 foreach $line (split "\n", $output) { 823 foreach $line (split "\n", $output) {
815 print $lineprefix . $line . "\n"; !! 824 print $lineprefix . $line . "\n";
816 } 825 }
817 } 826 }
818 827
819 sub output_function_rst(%) { 828 sub output_function_rst(%) {
820 my %args = %{$_[0]}; 829 my %args = %{$_[0]};
821 my ($parameter, $section); 830 my ($parameter, $section);
822 my $oldprefix = $lineprefix; 831 my $oldprefix = $lineprefix;
>> 832 my $start = "";
823 833
824 my $signature = ""; !! 834 if ($args{'typedef'}) {
>> 835 print ".. c:type:: ". $args{'function'} . "\n\n";
>> 836 print_lineno($declaration_start_line);
>> 837 print " **Typedef**: ";
>> 838 $lineprefix = "";
>> 839 output_highlight_rst($args{'purpose'});
>> 840 $start = "\n\n**Syntax**\n\n ``";
>> 841 } else {
>> 842 print ".. c:function:: ";
>> 843 }
825 if ($args{'functiontype'} ne "") { 844 if ($args{'functiontype'} ne "") {
826 $signature = $args{'functiontype'} . " !! 845 $start .= $args{'functiontype'} . " " . $args{'function'} . " (";
827 } else { 846 } else {
828 $signature = $args{'function'} . " ("; !! 847 $start .= $args{'function'} . " (";
829 } 848 }
>> 849 print $start;
830 850
831 my $count = 0; 851 my $count = 0;
832 foreach my $parameter (@{$args{'parameterl 852 foreach my $parameter (@{$args{'parameterlist'}}) {
833 if ($count ne 0) { !! 853 if ($count ne 0) {
834 $signature .= ", "; !! 854 print ", ";
835 } !! 855 }
836 $count++; !! 856 $count++;
837 $type = $args{'parametertypes'}{$param !! 857 $type = $args{'parametertypes'}{$parameter};
838 !! 858
839 if ($type =~ m/$function_pointer/) { !! 859 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
840 # pointer-to-function !! 860 # pointer-to-function
841 $signature .= $1 . $parameter . ") !! 861 print $1 . $parameter . ") (" . $2 . ")";
842 } else { !! 862 } else {
843 $signature .= $type; !! 863 print $type . " " . $parameter;
844 } !! 864 }
845 } 865 }
846 !! 866 if ($args{'typedef'}) {
847 $signature .= ")"; !! 867 print ");``\n\n";
848 <<
849 if ($sphinx_major < 3) { <<
850 if ($args{'typedef'}) { <<
851 print ".. c:type:: ". $args{'funct <<
852 print_lineno($declaration_start_li <<
853 print " **Typedef**: "; <<
854 $lineprefix = ""; <<
855 output_highlight_rst($args{'purpos <<
856 print "\n\n**Syntax**\n\n"; <<
857 print " ``$signature``\n\n"; <<
858 } else { <<
859 print ".. c:function:: $signature\ <<
860 } <<
861 } else { 868 } else {
862 if ($args{'typedef'} || $args{'functio !! 869 print ")\n\n";
863 print ".. c:macro:: ". $args{'func !! 870 print_lineno($declaration_start_line);
864 !! 871 $lineprefix = " ";
865 if ($args{'typedef'}) { !! 872 output_highlight_rst($args{'purpose'});
866 print_lineno($declaration_star !! 873 print "\n";
867 print " **Typedef**: "; <<
868 $lineprefix = ""; <<
869 output_highlight_rst($args{'pu <<
870 print "\n\n**Syntax**\n\n"; <<
871 print " ``$signature``\n\n"; <<
872 } else { <<
873 print "``$signature``\n\n"; <<
874 } <<
875 } else { <<
876 print ".. c:function:: $signature\ <<
877 } <<
878 } 874 }
879 875
880 if (!$args{'typedef'}) { !! 876 print "**Parameters**\n\n";
881 print_lineno($declaration_start_line); <<
882 $lineprefix = " "; <<
883 output_highlight_rst($args{'purpose'}) <<
884 print "\n"; <<
885 } <<
886 <<
887 # <<
888 # Put our descriptive text into a containe <<
889 # set the function prototypes apart. <<
890 # <<
891 print ".. container:: kernelindent\n\n"; <<
892 $lineprefix = " "; 877 $lineprefix = " ";
893 print $lineprefix . "**Parameters**\n\n"; <<
894 foreach $parameter (@{$args{'parameterlist 878 foreach $parameter (@{$args{'parameterlist'}}) {
895 my $parameter_name = $parameter; !! 879 my $parameter_name = $parameter;
896 $parameter_name =~ s/\[.*//; !! 880 $parameter_name =~ s/\[.*//;
897 $type = $args{'parametertypes'}{$param !! 881 $type = $args{'parametertypes'}{$parameter};
898 !! 882
899 if ($type ne "") { !! 883 if ($type ne "") {
900 print $lineprefix . "``$type``\n"; !! 884 print "``$type $parameter``\n";
901 } else { !! 885 } else {
902 print $lineprefix . "``$parameter` !! 886 print "``$parameter``\n";
903 } !! 887 }
904 888
905 print_lineno($parameterdesc_start_line 889 print_lineno($parameterdesc_start_lines{$parameter_name});
906 890
907 $lineprefix = " "; !! 891 if (defined($args{'parameterdescs'}{$parameter_name}) &&
908 if (defined($args{'parameterdescs'}{$p !! 892 $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
909 $args{'parameterdescs'}{$parameter !! 893 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
910 output_highlight_rst($args{'parame !! 894 } else {
911 } else { !! 895 print " *undescribed*\n";
912 print $lineprefix . "*undescribed* !! 896 }
913 } !! 897 print "\n";
914 $lineprefix = " "; <<
915 print "\n"; <<
916 } 898 }
917 899
918 output_section_rst(@_); <<
919 $lineprefix = $oldprefix; 900 $lineprefix = $oldprefix;
>> 901 output_section_rst(@_);
920 } 902 }
921 903
922 sub output_section_rst(%) { 904 sub output_section_rst(%) {
923 my %args = %{$_[0]}; 905 my %args = %{$_[0]};
924 my $section; 906 my $section;
925 my $oldprefix = $lineprefix; 907 my $oldprefix = $lineprefix;
>> 908 $lineprefix = "";
926 909
927 foreach $section (@{$args{'sectionlist'}}) 910 foreach $section (@{$args{'sectionlist'}}) {
928 print $lineprefix . "**$section**\n\n" !! 911 print "**$section**\n\n";
929 print_lineno($section_start_lines{$sec 912 print_lineno($section_start_lines{$section});
930 output_highlight_rst($args{'sections'} !! 913 output_highlight_rst($args{'sections'}{$section});
931 print "\n"; !! 914 print "\n";
932 } 915 }
933 print "\n"; 916 print "\n";
>> 917 $lineprefix = $oldprefix;
934 } 918 }
935 919
936 sub output_enum_rst(%) { 920 sub output_enum_rst(%) {
937 my %args = %{$_[0]}; 921 my %args = %{$_[0]};
938 my ($parameter); 922 my ($parameter);
939 my $oldprefix = $lineprefix; 923 my $oldprefix = $lineprefix;
940 my $count; 924 my $count;
941 my $outer; !! 925 my $name = "enum " . $args{'enum'};
942 926
943 if ($sphinx_major < 3) { !! 927 print "\n\n.. c:type:: " . $name . "\n\n";
944 my $name = "enum " . $args{'enum'}; <<
945 print "\n\n.. c:type:: " . $name . "\n <<
946 } else { <<
947 my $name = $args{'enum'}; <<
948 print "\n\n.. c:enum:: " . $name . "\n <<
949 } <<
950 print_lineno($declaration_start_line); 928 print_lineno($declaration_start_line);
951 $lineprefix = " "; !! 929 $lineprefix = " ";
952 output_highlight_rst($args{'purpose'}); 930 output_highlight_rst($args{'purpose'});
953 print "\n"; 931 print "\n";
954 932
955 print ".. container:: kernelindent\n\n"; !! 933 print "**Constants**\n\n";
956 $outer = $lineprefix . " "; !! 934 $lineprefix = " ";
957 $lineprefix = $outer . " "; <<
958 print $outer . "**Constants**\n\n"; <<
959 foreach $parameter (@{$args{'parameterlist 935 foreach $parameter (@{$args{'parameterlist'}}) {
960 print $outer . "``$parameter``\n"; !! 936 print "``$parameter``\n";
961 !! 937 if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
962 if ($args{'parameterdescs'}{$parameter !! 938 output_highlight_rst($args{'parameterdescs'}{$parameter});
963 output_highlight_rst($args{'parame !! 939 } else {
964 } else { !! 940 print " *undescribed*\n";
965 print $lineprefix . "*undescribed* !! 941 }
966 } !! 942 print "\n";
967 print "\n"; <<
968 } 943 }
969 print "\n"; !! 944
970 $lineprefix = $oldprefix; 945 $lineprefix = $oldprefix;
971 output_section_rst(@_); 946 output_section_rst(@_);
972 } 947 }
973 948
974 sub output_typedef_rst(%) { 949 sub output_typedef_rst(%) {
975 my %args = %{$_[0]}; 950 my %args = %{$_[0]};
976 my ($parameter); 951 my ($parameter);
977 my $oldprefix = $lineprefix; 952 my $oldprefix = $lineprefix;
978 my $name; !! 953 my $name = "typedef " . $args{'typedef'};
979 954
980 if ($sphinx_major < 3) { <<
981 $name = "typedef " . $args{'typedef'}; <<
982 } else { <<
983 $name = $args{'typedef'}; <<
984 } <<
985 print "\n\n.. c:type:: " . $name . "\n\n"; 955 print "\n\n.. c:type:: " . $name . "\n\n";
986 print_lineno($declaration_start_line); 956 print_lineno($declaration_start_line);
987 $lineprefix = " "; 957 $lineprefix = " ";
988 output_highlight_rst($args{'purpose'}); 958 output_highlight_rst($args{'purpose'});
989 print "\n"; 959 print "\n";
990 960
991 $lineprefix = $oldprefix; 961 $lineprefix = $oldprefix;
992 output_section_rst(@_); 962 output_section_rst(@_);
993 } 963 }
994 964
995 sub output_struct_rst(%) { 965 sub output_struct_rst(%) {
996 my %args = %{$_[0]}; 966 my %args = %{$_[0]};
997 my ($parameter); 967 my ($parameter);
998 my $oldprefix = $lineprefix; 968 my $oldprefix = $lineprefix;
>> 969 my $name = $args{'type'} . " " . $args{'struct'};
999 970
1000 if ($sphinx_major < 3) { !! 971 print "\n\n.. c:type:: " . $name . "\n\n";
1001 my $name = $args{'type'} . " " . $arg <<
1002 print "\n\n.. c:type:: " . $name . "\ <<
1003 } else { <<
1004 my $name = $args{'struct'}; <<
1005 if ($args{'type'} eq 'union') { <<
1006 print "\n\n.. c:union:: " . $name <<
1007 } else { <<
1008 print "\n\n.. c:struct:: " . $nam <<
1009 } <<
1010 } <<
1011 print_lineno($declaration_start_line); 972 print_lineno($declaration_start_line);
1012 $lineprefix = " "; !! 973 $lineprefix = " ";
1013 output_highlight_rst($args{'purpose'}); 974 output_highlight_rst($args{'purpose'});
1014 print "\n"; 975 print "\n";
1015 976
1016 print ".. container:: kernelindent\n\n"; !! 977 print "**Definition**\n\n";
1017 print $lineprefix . "**Definition**::\n\n !! 978 print "::\n\n";
1018 my $declaration = $args{'definition'}; 979 my $declaration = $args{'definition'};
1019 $lineprefix = $lineprefix . " "; !! 980 $declaration =~ s/\t/ /g;
1020 $declaration =~ s/\t/$lineprefix/g; !! 981 print " " . $args{'type'} . " " . $args{'struct'} . " {\n$declaration };\n\n";
1021 print $lineprefix . $args{'type'} . " " . <<
1022 982
>> 983 print "**Members**\n\n";
1023 $lineprefix = " "; 984 $lineprefix = " ";
1024 print $lineprefix . "**Members**\n\n"; <<
1025 foreach $parameter (@{$args{'parameterlis 985 foreach $parameter (@{$args{'parameterlist'}}) {
1026 ($parameter =~ /^#/) && next; !! 986 ($parameter =~ /^#/) && next;
1027 987
1028 my $parameter_name = $parameter; !! 988 my $parameter_name = $parameter;
1029 $parameter_name =~ s/\[.*//; !! 989 $parameter_name =~ s/\[.*//;
1030 990
1031 ($args{'parameterdescs'}{$parameter_n !! 991 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1032 $type = $args{'parametertypes'}{$para !! 992 $type = $args{'parametertypes'}{$parameter};
1033 print_lineno($parameterdesc_start_lin 993 print_lineno($parameterdesc_start_lines{$parameter_name});
1034 print $lineprefix . "``" . $parameter !! 994 print "``" . $parameter . "``\n";
1035 $lineprefix = " "; !! 995 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1036 output_highlight_rst($args{'parameter !! 996 print "\n";
1037 $lineprefix = " "; <<
1038 print "\n"; <<
1039 } 997 }
1040 print "\n"; 998 print "\n";
1041 999
1042 $lineprefix = $oldprefix; 1000 $lineprefix = $oldprefix;
1043 output_section_rst(@_); 1001 output_section_rst(@_);
1044 } 1002 }
1045 1003
1046 ## none mode output functions 1004 ## none mode output functions
1047 1005
1048 sub output_function_none(%) { 1006 sub output_function_none(%) {
1049 } 1007 }
1050 1008
1051 sub output_enum_none(%) { 1009 sub output_enum_none(%) {
1052 } 1010 }
1053 1011
1054 sub output_typedef_none(%) { 1012 sub output_typedef_none(%) {
1055 } 1013 }
1056 1014
1057 sub output_struct_none(%) { 1015 sub output_struct_none(%) {
1058 } 1016 }
1059 1017
1060 sub output_blockhead_none(%) { 1018 sub output_blockhead_none(%) {
1061 } 1019 }
1062 1020
1063 ## 1021 ##
1064 # generic output function for all types (func 1022 # generic output function for all types (function, struct/union, typedef, enum);
1065 # calls the generated, variable output_ funct 1023 # calls the generated, variable output_ function name based on
1066 # functype and output_mode 1024 # functype and output_mode
1067 sub output_declaration { 1025 sub output_declaration {
1068 no strict 'refs'; 1026 no strict 'refs';
1069 my $name = shift; 1027 my $name = shift;
1070 my $functype = shift; 1028 my $functype = shift;
1071 my $func = "output_${functype}_$output_mo 1029 my $func = "output_${functype}_$output_mode";
1072 <<
1073 return if (defined($nosymbol_table{$name} <<
1074 <<
1075 if (($output_selection == OUTPUT_ALL) || 1030 if (($output_selection == OUTPUT_ALL) ||
1076 (($output_selection == OUTPUT_INCLUDE !! 1031 (($output_selection == OUTPUT_INCLUDE ||
1077 $output_selection == OUTPUT_EXPORTE !! 1032 $output_selection == OUTPUT_EXPORTED) &&
1078 defined($function_table{$name})) || !! 1033 defined($function_table{$name})) ||
1079 ($output_selection == OUTPUT_INTERNAL !! 1034 (($output_selection == OUTPUT_EXCLUDE ||
1080 !($functype eq "function" && defined !! 1035 $output_selection == OUTPUT_INTERNAL) &&
>> 1036 !($functype eq "function" && defined($function_table{$name}))))
1081 { 1037 {
1082 &$func(@_); !! 1038 &$func(@_);
1083 $section_counter++; !! 1039 $section_counter++;
1084 } 1040 }
1085 } 1041 }
1086 1042
1087 ## 1043 ##
1088 # generic output function - calls the right o 1044 # generic output function - calls the right one based on current output mode.
1089 sub output_blockhead { 1045 sub output_blockhead {
1090 no strict 'refs'; 1046 no strict 'refs';
1091 my $func = "output_blockhead_" . $output_ 1047 my $func = "output_blockhead_" . $output_mode;
1092 &$func(@_); 1048 &$func(@_);
1093 $section_counter++; 1049 $section_counter++;
1094 } 1050 }
1095 1051
1096 ## 1052 ##
1097 # takes a declaration (struct, union, enum, t 1053 # takes a declaration (struct, union, enum, typedef) and
1098 # invokes the right handler. NOT called for f 1054 # invokes the right handler. NOT called for functions.
1099 sub dump_declaration($$) { 1055 sub dump_declaration($$) {
1100 no strict 'refs'; 1056 no strict 'refs';
1101 my ($prototype, $file) = @_; 1057 my ($prototype, $file) = @_;
1102 my $func = "dump_" . $decl_type; 1058 my $func = "dump_" . $decl_type;
1103 &$func(@_); 1059 &$func(@_);
1104 } 1060 }
1105 1061
1106 sub dump_union($$) { 1062 sub dump_union($$) {
1107 dump_struct(@_); 1063 dump_struct(@_);
1108 } 1064 }
1109 1065
1110 sub dump_struct($$) { 1066 sub dump_struct($$) {
1111 my $x = shift; 1067 my $x = shift;
1112 my $file = shift; 1068 my $file = shift;
1113 my $decl_type; <<
1114 my $members; <<
1115 my $type = qr{struct|union}; <<
1116 # For capturing struct/union definition b <<
1117 my $qualifiers = qr{$attribute|__packed|_ <<
1118 my $definition_body = qr{\{(.*)\}\s*$qual <<
1119 my $struct_members = qr{($type)([^\{\};]+ <<
1120 1069
1121 if ($x =~ /($type)\s+(\w+)\s*$definition_ !! 1070 if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|____cacheline_aligned_in_smp|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/) {
1122 $decl_type = $1; !! 1071 my $decl_type = $1;
1123 $declaration_name = $2; !! 1072 $declaration_name = $2;
1124 $members = $3; !! 1073 my $members = $3;
1125 } elsif ($x =~ /typedef\s+($type)\s*$defi !! 1074
1126 $decl_type = $1; !! 1075 # ignore members marked private:
1127 $declaration_name = $3; !! 1076 $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
1128 $members = $2; !! 1077 $members =~ s/\/\*\s*private:.*//gosi;
1129 } !! 1078 # strip comments:
1130 !! 1079 $members =~ s/\/\*.*?\*\///gos;
1131 if ($members) { !! 1080 # strip attributes
1132 if ($identifier ne $declaration_name) !! 1081 $members =~ s/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)/ /gi;
1133 emit_warning("${file}:$.", "expec !! 1082 $members =~ s/\s*__aligned\s*\([^;]*\)/ /gos;
1134 return; !! 1083 $members =~ s/\s*__packed\s*/ /gos;
1135 } !! 1084 $members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos;
1136 !! 1085 $members =~ s/\s*____cacheline_aligned_in_smp/ /gos;
1137 # ignore members marked private: !! 1086 # replace DECLARE_BITMAP
1138 $members =~ s/\/\*\s*private:.*?\/\*\ !! 1087 $members =~ s/DECLARE_BITMAP\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
1139 $members =~ s/\/\*\s*private:.*//gosi !! 1088 # replace DECLARE_HASHTABLE
1140 # strip comments: !! 1089 $members =~ s/DECLARE_HASHTABLE\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
1141 $members =~ s/\/\*.*?\*\///gos; !! 1090 # replace DECLARE_KFIFO
1142 # strip attributes !! 1091 $members =~ s/DECLARE_KFIFO\s*\(([^,)]+),\s*([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos;
1143 $members =~ s/\s*$attribute/ /gi; !! 1092 # replace DECLARE_KFIFO_PTR
1144 $members =~ s/\s*__aligned\s*\([^;]*\ !! 1093 $members =~ s/DECLARE_KFIFO_PTR\s*\(([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos;
1145 $members =~ s/\s*__counted_by\s*\([^; !! 1094
1146 $members =~ s/\s*__counted_by_(le|be) !! 1095 my $declaration = $members;
1147 $members =~ s/\s*__packed\s*/ /gos; !! 1096
1148 $members =~ s/\s*CRYPTO_MINALIGN_ATTR !! 1097 # Split nested struct/union elements as newer ones
1149 $members =~ s/\s*____cacheline_aligne !! 1098 while ($members =~ m/(struct|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;/) {
1150 $members =~ s/\s*____cacheline_aligne !! 1099 my $newmember;
1151 # unwrap struct_group(): !! 1100 my $maintype = $1;
1152 # - first eat non-declaration paramet !! 1101 my $ids = $4;
1153 # - then remove macro, outer parens, !! 1102 my $content = $3;
1154 $members =~ s/\bstruct_group\s*\(([^, !! 1103 foreach my $id(split /,/, $ids) {
1155 $members =~ s/\bstruct_group_attr\s*\ !! 1104 $newmember .= "$maintype $id; ";
1156 $members =~ s/\bstruct_group_tagged\s !! 1105
1157 $members =~ s/\b__struct_group\s*\(([ !! 1106 $id =~ s/[:\[].*//;
1158 $members =~ s/\bSTRUCT_GROUP(\(((?:(? !! 1107 $id =~ s/^\s*\**(\S+)\s*/$1/;
1159 !! 1108 foreach my $arg (split /;/, $content) {
1160 my $args = qr{([^,)]+)}; !! 1109 next if ($arg =~ m/^\s*$/);
1161 # replace DECLARE_BITMAP !! 1110 if ($arg =~ m/^([^\(]+\(\*?\s*)([\w\.]*)(\s*\).*)/) {
1162 $members =~ s/__ETHTOOL_DECLARE_LINK_ !! 1111 # pointer-to-function
1163 $members =~ s/DECLARE_PHY_INTERFACE_M !! 1112 my $type = $1;
1164 $members =~ s/DECLARE_BITMAP\s*\($arg !! 1113 my $name = $2;
1165 # replace DECLARE_HASHTABLE !! 1114 my $extra = $3;
1166 $members =~ s/DECLARE_HASHTABLE\s*\($ !! 1115 next if (!$name);
1167 # replace DECLARE_KFIFO !! 1116 if ($id =~ m/^\s*$/) {
1168 $members =~ s/DECLARE_KFIFO\s*\($args !! 1117 # anonymous struct/union
1169 # replace DECLARE_KFIFO_PTR !! 1118 $newmember .= "$type$name$extra; ";
1170 $members =~ s/DECLARE_KFIFO_PTR\s*\($ !! 1119 } else {
1171 # replace DECLARE_FLEX_ARRAY !! 1120 $newmember .= "$type$id.$name$extra; ";
1172 $members =~ s/(?:__)?DECLARE_FLEX_ARR !! 1121 }
1173 #replace DEFINE_DMA_UNMAP_ADDR !! 1122 } else {
1174 $members =~ s/DEFINE_DMA_UNMAP_ADDR\s !! 1123 my $type;
1175 #replace DEFINE_DMA_UNMAP_LEN !! 1124 my $names;
1176 $members =~ s/DEFINE_DMA_UNMAP_LEN\s* !! 1125 $arg =~ s/^\s+//;
1177 my $declaration = $members; !! 1126 $arg =~ s/\s+$//;
1178 !! 1127 # Handle bitmaps
1179 # Split nested struct/union elements !! 1128 $arg =~ s/:\s*\d+\s*//g;
1180 while ($members =~ m/$struct_members/ !! 1129 # Handle arrays
1181 my $newmember; !! 1130 $arg =~ s/\[.*\]//g;
1182 my $maintype = $1; !! 1131 # The type may have multiple words,
1183 my $ids = $4; !! 1132 # and multiple IDs can be defined, like:
1184 my $content = $3; !! 1133 # const struct foo, *bar, foobar
1185 foreach my $id(split /,/, $ids) { !! 1134 # So, we remove spaces when parsing the
1186 $newmember .= "$maintype $id; !! 1135 # names, in order to match just names
1187 !! 1136 # and commas for the names
1188 $id =~ s/[:\[].*//; !! 1137 $arg =~ s/\s*,\s*/,/g;
1189 $id =~ s/^\s*\**(\S+)\s*/$1/; !! 1138 if ($arg =~ m/(.*)\s+([\S+,]+)/) {
1190 foreach my $arg (split /;/, $ !! 1139 $type = $1;
1191 next if ($arg =~ m/^\s*$/ !! 1140 $names = $2;
1192 if ($arg =~ m/^([^\(]+\(\ !! 1141 } else {
1193 # pointer-to-function !! 1142 $newmember .= "$arg; ";
1194 my $type = $1; !! 1143 next;
1195 my $name = $2; !! 1144 }
1196 my $extra = $3; !! 1145 foreach my $name (split /,/, $names) {
1197 next if (!$name); !! 1146 $name =~ s/^\s*\**(\S+)\s*/$1/;
1198 if ($id =~ m/^\s*$/) !! 1147 next if (($name =~ m/^\s*$/));
1199 # anonymous struc !! 1148 if ($id =~ m/^\s*$/) {
1200 $newmember .= "$t !! 1149 # anonymous struct/union
1201 } else { !! 1150 $newmember .= "$type $name; ";
1202 $newmember .= "$t !! 1151 } else {
1203 } !! 1152 $newmember .= "$type $id.$name; ";
1204 } else { !! 1153 }
1205 my $type; !! 1154 }
1206 my $names; !! 1155 }
1207 $arg =~ s/^\s+//; !! 1156 }
1208 $arg =~ s/\s+$//; !! 1157 }
1209 # Handle bitmaps !! 1158 $members =~ s/(struct|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;/$newmember/;
1210 $arg =~ s/:\s*\d+\s*/ !! 1159 }
1211 # Handle arrays !! 1160
1212 $arg =~ s/\[.*\]//g; !! 1161 # Ignore other nested elements, like enums
1213 # The type may have m !! 1162 $members =~ s/(\{[^\{\}]*\})//g;
1214 # and multiple IDs ca !! 1163
1215 # const struct foo !! 1164 create_parameterlist($members, ';', $file, $declaration_name);
1216 # So, we remove space !! 1165 check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual);
1217 # names, in order to !! 1166
1218 # and commas for the !! 1167 # Adjust declaration for better display
1219 $arg =~ s/\s*,\s*/,/g !! 1168 $declaration =~ s/([\{;])/$1\n/g;
1220 if ($arg =~ m/(.*)\s+ !! 1169 $declaration =~ s/\}\s+;/};/g;
1221 $type = $1; !! 1170 # Better handle inlined enums
1222 $names = $2; !! 1171 do {} while ($declaration =~ s/(enum\s+\{[^\}]+),([^\n])/$1,\n$2/);
1223 } else { !! 1172
1224 $newmember .= "$a !! 1173 my @def_args = split /\n/, $declaration;
1225 next; !! 1174 my $level = 1;
1226 } !! 1175 $declaration = "";
1227 foreach my $name (spl !! 1176 foreach my $clause (@def_args) {
1228 $name =~ s/^\s*\* !! 1177 $clause =~ s/^\s+//;
1229 next if (($name = !! 1178 $clause =~ s/\s+$//;
1230 if ($id =~ m/^\s* !! 1179 $clause =~ s/\s+/ /;
1231 # anonymous s !! 1180 next if (!$clause);
1232 $newmember .= !! 1181 $level-- if ($clause =~ m/(\})/ && $level > 1);
1233 } else { !! 1182 if (!($clause =~ m/^\s*#/)) {
1234 $newmember .= !! 1183 $declaration .= "\t" x $level;
1235 } !! 1184 }
1236 } !! 1185 $declaration .= "\t" . $clause . "\n";
1237 } !! 1186 $level++ if ($clause =~ m/(\{)/ && !($clause =~m/\}/));
1238 } !! 1187 }
1239 } !! 1188 output_declaration($declaration_name,
1240 $members =~ s/$struct_members/$ne !! 1189 'struct',
1241 } !! 1190 {'struct' => $declaration_name,
1242 !! 1191 'module' => $modulename,
1243 # Ignore other nested elements, like !! 1192 'definition' => $declaration,
1244 $members =~ s/(\{[^\{\}]*\})//g; !! 1193 'parameterlist' => \@parameterlist,
1245 !! 1194 'parameterdescs' => \%parameterdescs,
1246 create_parameterlist($members, ';', $ !! 1195 'parametertypes' => \%parametertypes,
1247 check_sections($file, $declaration_na !! 1196 'sectionlist' => \@sectionlist,
1248 !! 1197 'sections' => \%sections,
1249 # Adjust declaration for better displ !! 1198 'purpose' => $declaration_purpose,
1250 $declaration =~ s/([\{;])/$1\n/g; !! 1199 'type' => $decl_type
1251 $declaration =~ s/\}\s+;/};/g; !! 1200 });
1252 # Better handle inlined enums !! 1201 }
1253 do {} while ($declaration =~ s/(enum\ !! 1202 else {
1254 !! 1203 print STDERR "${file}:$.: error: Cannot parse struct or union!\n";
1255 my @def_args = split /\n/, $declarati !! 1204 ++$errors;
1256 my $level = 1; <<
1257 $declaration = ""; <<
1258 foreach my $clause (@def_args) { <<
1259 $clause =~ s/^\s+//; <<
1260 $clause =~ s/\s+$//; <<
1261 $clause =~ s/\s+/ /; <<
1262 next if (!$clause); <<
1263 $level-- if ($clause =~ m/(\})/ & <<
1264 if (!($clause =~ m/^\s*#/)) { <<
1265 $declaration .= "\t" x $level <<
1266 } <<
1267 $declaration .= "\t" . $clause . <<
1268 $level++ if ($clause =~ m/(\{)/ & <<
1269 } <<
1270 output_declaration($declaration_name, <<
1271 'struct', <<
1272 {'struct' => $declaration_ <<
1273 'module' => $modulename, <<
1274 'definition' => $declarat <<
1275 'parameterlist' => \@para <<
1276 'parameterdescs' => \%par <<
1277 'parametertypes' => \%par <<
1278 'sectionlist' => \@sectio <<
1279 'sections' => \%sections, <<
1280 'purpose' => $declaration <<
1281 'type' => $decl_type <<
1282 }); <<
1283 } else { <<
1284 print STDERR "${file}:$.: error: Cann <<
1285 ++$errors; <<
1286 } 1205 }
1287 } 1206 }
1288 1207
1289 1208
1290 sub show_warnings($$) { 1209 sub show_warnings($$) {
1291 my $functype = shift; !! 1210 my $functype = shift;
1292 my $name = shift; !! 1211 my $name = shift;
1293 <<
1294 return 0 if (defined($nosymbol_table{$nam <<
1295 1212
1296 return 1 if ($output_selection == OUTPUT_ !! 1213 return 1 if ($output_selection == OUTPUT_ALL);
1297 1214
1298 if ($output_selection == OUTPUT_EXPORTED) !! 1215 if ($output_selection == OUTPUT_EXPORTED) {
1299 if (defined($function_table{$name})) !! 1216 if (defined($function_table{$name})) {
1300 return 1; !! 1217 return 1;
1301 } else { !! 1218 } else {
1302 return 0; !! 1219 return 0;
1303 } !! 1220 }
1304 } !! 1221 }
1305 if ($output_selection == OUTPUT_INTERNAL) !! 1222 if ($output_selection == OUTPUT_INTERNAL) {
1306 if (!($functype eq "function" && defi !! 1223 if (!($functype eq "function" && defined($function_table{$name}))) {
1307 return 1; !! 1224 return 1;
1308 } else { !! 1225 } else {
1309 return 0; !! 1226 return 0;
1310 } !! 1227 }
1311 } !! 1228 }
1312 if ($output_selection == OUTPUT_INCLUDE) !! 1229 if ($output_selection == OUTPUT_INCLUDE) {
1313 if (defined($function_table{$name})) !! 1230 if (defined($function_table{$name})) {
1314 return 1; !! 1231 return 1;
1315 } else { !! 1232 } else {
1316 return 0; !! 1233 return 0;
1317 } !! 1234 }
1318 } !! 1235 }
1319 die("Please add the new output type at sh !! 1236 if ($output_selection == OUTPUT_EXCLUDE) {
>> 1237 if (!defined($function_table{$name})) {
>> 1238 return 1;
>> 1239 } else {
>> 1240 return 0;
>> 1241 }
>> 1242 }
>> 1243 die("Please add the new output type at show_warnings()");
1320 } 1244 }
1321 1245
1322 sub dump_enum($$) { 1246 sub dump_enum($$) {
1323 my $x = shift; 1247 my $x = shift;
1324 my $file = shift; 1248 my $file = shift;
1325 my $members; <<
1326 <<
1327 # ignore members marked private: <<
1328 $x =~ s/\/\*\s*private:.*?\/\*\s*public:. <<
1329 $x =~ s/\/\*\s*private:.*}/}/gosi; <<
1330 1249
1331 $x =~ s@/\*.*?\*/@@gos; # strip comme 1250 $x =~ s@/\*.*?\*/@@gos; # strip comments.
1332 # strip #define macros inside enums 1251 # strip #define macros inside enums
1333 $x =~ s@#\s*((define|ifdef|if)\s+|endif)[ !! 1252 $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
1334 1253
1335 if ($x =~ /typedef\s+enum\s*\{(.*)\}\s*(\ !! 1254 if ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) {
1336 $declaration_name = $2; !! 1255 $declaration_name = $1;
1337 $members = $1; !! 1256 my $members = $2;
1338 } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) !! 1257 my %_members;
1339 $declaration_name = $1; !! 1258
1340 $members = $2; !! 1259 $members =~ s/\s+$//;
1341 } !! 1260
1342 !! 1261 foreach my $arg (split ',', $members) {
1343 if ($members) { !! 1262 $arg =~ s/^\s*(\w+).*/$1/;
1344 if ($identifier ne $declaration_name) !! 1263 push @parameterlist, $arg;
1345 if ($identifier eq "") { !! 1264 if (!$parameterdescs{$arg}) {
1346 emit_warning("${file}:$.", "w !! 1265 $parameterdescs{$arg} = $undescribed;
1347 } else { !! 1266 if (show_warnings("enum", $declaration_name)) {
1348 emit_warning("${file}:$.", "e !! 1267 print STDERR "${file}:$.: warning: Enum value '$arg' not described in enum '$declaration_name'\n";
1349 } !! 1268 }
1350 return; !! 1269 }
1351 } !! 1270 $_members{$arg} = 1;
1352 $declaration_name = "(anonymous)" if !! 1271 }
1353 !! 1272
1354 my %_members; !! 1273 while (my ($k, $v) = each %parameterdescs) {
1355 !! 1274 if (!exists($_members{$k})) {
1356 $members =~ s/\s+$//; !! 1275 if (show_warnings("enum", $declaration_name)) {
1357 $members =~ s/\([^;]*?[\)]//g; !! 1276 print STDERR "${file}:$.: warning: Excess enum value '$k' description in '$declaration_name'\n";
1358 !! 1277 }
1359 foreach my $arg (split ',', $members) !! 1278 }
1360 $arg =~ s/^\s*(\w+).*/$1/; !! 1279 }
1361 push @parameterlist, $arg; !! 1280
1362 if (!$parameterdescs{$arg}) { !! 1281 output_declaration($declaration_name,
1363 $parameterdescs{$arg} = $unde !! 1282 'enum',
1364 if (show_warnings("enum", $de !! 1283 {'enum' => $declaration_name,
1365 emit_warning("${file}:$." !! 1284 'module' => $modulename,
1366 } !! 1285 'parameterlist' => \@parameterlist,
1367 } !! 1286 'parameterdescs' => \%parameterdescs,
1368 $_members{$arg} = 1; !! 1287 'sectionlist' => \@sectionlist,
1369 } !! 1288 'sections' => \%sections,
1370 !! 1289 'purpose' => $declaration_purpose
1371 while (my ($k, $v) = each %parameterd !! 1290 });
1372 if (!exists($_members{$k})) { !! 1291 }
1373 if (show_warnings("enum", $de !! 1292 else {
1374 emit_warning("${file}:$." !! 1293 print STDERR "${file}:$.: error: Cannot parse enum!\n";
1375 } !! 1294 ++$errors;
1376 } <<
1377 } <<
1378 <<
1379 output_declaration($declaration_name, <<
1380 'enum', <<
1381 {'enum' => $declar <<
1382 'module' => $modu <<
1383 'parameterlist' = <<
1384 'parameterdescs' <<
1385 'sectionlist' => <<
1386 'sections' => \%s <<
1387 'purpose' => $dec <<
1388 }); <<
1389 } else { <<
1390 print STDERR "${file}:$.: error: Cann <<
1391 ++$errors; <<
1392 } 1295 }
1393 } 1296 }
1394 1297
1395 my $typedef_type = qr { ((?:\s+[\w\*]+\b){1,8 <<
1396 my $typedef_ident = qr { \*?\s*(\w\S+)\s* }x; <<
1397 my $typedef_args = qr { \s*\((.*)\); }x; <<
1398 <<
1399 my $typedef1 = qr { typedef$typedef_type\($ty <<
1400 my $typedef2 = qr { typedef$typedef_type$type <<
1401 <<
1402 sub dump_typedef($$) { 1298 sub dump_typedef($$) {
1403 my $x = shift; 1299 my $x = shift;
1404 my $file = shift; 1300 my $file = shift;
1405 1301
1406 $x =~ s@/\*.*?\*/@@gos; # strip comme 1302 $x =~ s@/\*.*?\*/@@gos; # strip comments.
1407 1303
1408 # Parse function typedef prototypes !! 1304 # Parse function prototypes
1409 if ($x =~ $typedef1 || $x =~ $typedef2) { !! 1305 if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
1410 $return_type = $1; !! 1306 $x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
1411 $declaration_name = $2; !! 1307
1412 my $args = $3; !! 1308 # Function typedefs
1413 $return_type =~ s/^\s+//; !! 1309 $return_type = $1;
1414 !! 1310 $declaration_name = $2;
1415 if ($identifier ne $declaration_name) !! 1311 my $args = $3;
1416 emit_warning("${file}:$.", "expec !! 1312
1417 return; !! 1313 create_parameterlist($args, ',', $file, $declaration_name);
1418 } !! 1314
1419 !! 1315 output_declaration($declaration_name,
1420 create_parameterlist($args, ',', $fil !! 1316 'function',
1421 !! 1317 {'function' => $declaration_name,
1422 output_declaration($declaration_name, !! 1318 'typedef' => 1,
1423 'function', !! 1319 'module' => $modulename,
1424 {'function' => $de !! 1320 'functiontype' => $return_type,
1425 'typedef' => 1, !! 1321 'parameterlist' => \@parameterlist,
1426 'module' => $modu !! 1322 'parameterdescs' => \%parameterdescs,
1427 'functiontype' => !! 1323 'parametertypes' => \%parametertypes,
1428 'parameterlist' = !! 1324 'sectionlist' => \@sectionlist,
1429 'parameterdescs' !! 1325 'sections' => \%sections,
1430 'parametertypes' !! 1326 'purpose' => $declaration_purpose
1431 'sectionlist' => !! 1327 });
1432 'sections' => \%s !! 1328 return;
1433 'purpose' => $dec <<
1434 }); <<
1435 return; <<
1436 } 1329 }
1437 1330
1438 while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\ 1331 while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
1439 $x =~ s/\(*.\)\s*;$/;/; !! 1332 $x =~ s/\(*.\)\s*;$/;/;
1440 $x =~ s/\[*.\]\s*;$/;/; !! 1333 $x =~ s/\[*.\]\s*;$/;/;
1441 } 1334 }
1442 1335
1443 if ($x =~ /typedef.*\s+(\w+)\s*;/) { 1336 if ($x =~ /typedef.*\s+(\w+)\s*;/) {
1444 $declaration_name = $1; !! 1337 $declaration_name = $1;
1445 <<
1446 if ($identifier ne $declaration_name) <<
1447 emit_warning("${file}:$.", "expec <<
1448 return; <<
1449 } <<
1450 1338
1451 output_declaration($declaration_name, !! 1339 output_declaration($declaration_name,
1452 'typedef', !! 1340 'typedef',
1453 {'typedef' => $dec !! 1341 {'typedef' => $declaration_name,
1454 'module' => $modu !! 1342 'module' => $modulename,
1455 'sectionlist' => !! 1343 'sectionlist' => \@sectionlist,
1456 'sections' => \%s !! 1344 'sections' => \%sections,
1457 'purpose' => $dec !! 1345 'purpose' => $declaration_purpose
1458 }); !! 1346 });
1459 } else { !! 1347 }
1460 print STDERR "${file}:$.: error: Cann !! 1348 else {
1461 ++$errors; !! 1349 print STDERR "${file}:$.: error: Cannot parse typedef!\n";
>> 1350 ++$errors;
1462 } 1351 }
1463 } 1352 }
1464 1353
1465 sub save_struct_actual($) { 1354 sub save_struct_actual($) {
1466 my $actual = shift; 1355 my $actual = shift;
1467 1356
1468 # strip all spaces from the actual param 1357 # strip all spaces from the actual param so that it looks like one string item
1469 $actual =~ s/\s*//g; 1358 $actual =~ s/\s*//g;
1470 $struct_actual = $struct_actual . $actual 1359 $struct_actual = $struct_actual . $actual . " ";
1471 } 1360 }
1472 1361
1473 sub create_parameterlist($$$$) { 1362 sub create_parameterlist($$$$) {
1474 my $args = shift; 1363 my $args = shift;
1475 my $splitter = shift; 1364 my $splitter = shift;
1476 my $file = shift; 1365 my $file = shift;
1477 my $declaration_name = shift; 1366 my $declaration_name = shift;
1478 my $type; 1367 my $type;
1479 my $param; 1368 my $param;
1480 1369
1481 # temporarily replace commas inside funct 1370 # temporarily replace commas inside function pointer definition
1482 my $arg_expr = qr{\([^\),]+}; !! 1371 while ($args =~ /(\([^\),]+),/) {
1483 while ($args =~ /$arg_expr,/) { !! 1372 $args =~ s/(\([^\),]+),/$1#/g;
1484 $args =~ s/($arg_expr),/$1#/g; <<
1485 } 1373 }
1486 1374
1487 foreach my $arg (split($splitter, $args)) 1375 foreach my $arg (split($splitter, $args)) {
1488 # strip comments !! 1376 # strip comments
1489 $arg =~ s/\/\*.*\*\///; !! 1377 $arg =~ s/\/\*.*\*\///;
1490 # ignore argument attributes !! 1378 # strip leading/trailing spaces
1491 $arg =~ s/\sPOS0?\s/ /; !! 1379 $arg =~ s/^\s*//;
1492 # strip leading/trailing spaces !! 1380 $arg =~ s/\s*$//;
1493 $arg =~ s/^\s*//; !! 1381 $arg =~ s/\s+/ /;
1494 $arg =~ s/\s*$//; !! 1382
1495 $arg =~ s/\s+/ /; !! 1383 if ($arg =~ /^#/) {
1496 !! 1384 # Treat preprocessor directive as a typeless variable just to fill
1497 if ($arg =~ /^#/) { !! 1385 # corresponding data structures "correctly". Catch it later in
1498 # Treat preprocessor directive as !! 1386 # output_* subs.
1499 # corresponding data structures " !! 1387 push_parameter($arg, "", $file);
1500 # output_* subs. !! 1388 } elsif ($arg =~ m/\(.+\)\s*\(/) {
1501 push_parameter($arg, "", "", $fil !! 1389 # pointer-to-function
1502 } elsif ($arg =~ m/\(.+\)\s*\(/) { !! 1390 $arg =~ tr/#/,/;
1503 # pointer-to-function !! 1391 $arg =~ m/[^\(]+\(\*?\s*([\w\.]*)\s*\)/;
1504 $arg =~ tr/#/,/; !! 1392 $param = $1;
1505 $arg =~ m/[^\(]+\(\*?\s*([\w\[\]\ !! 1393 $type = $arg;
1506 $param = $1; !! 1394 $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
1507 $type = $arg; !! 1395 save_struct_actual($param);
1508 $type =~ s/([^\(]+\(\*?)\s*$param !! 1396 push_parameter($param, $type, $file, $declaration_name);
1509 save_struct_actual($param); !! 1397 } elsif ($arg) {
1510 push_parameter($param, $type, $ar !! 1398 $arg =~ s/\s*:\s*/:/g;
1511 } elsif ($arg =~ m/\(.+\)\s*\[/) { !! 1399 $arg =~ s/\s*\[/\[/g;
1512 # array-of-pointers !! 1400
1513 $arg =~ tr/#/,/; !! 1401 my @args = split('\s*,\s*', $arg);
1514 $arg =~ m/[^\(]+\(\s*\*\s*([\w\[\ !! 1402 if ($args[0] =~ m/\*/) {
1515 $param = $1; !! 1403 $args[0] =~ s/(\*+)\s*/ $1/;
1516 $type = $arg; !! 1404 }
1517 $type =~ s/([^\(]+\(\*?)\s*$param !! 1405
1518 save_struct_actual($param); !! 1406 my @first_arg;
1519 push_parameter($param, $type, $ar !! 1407 if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
1520 } elsif ($arg) { !! 1408 shift @args;
1521 $arg =~ s/\s*:\s*/:/g; !! 1409 push(@first_arg, split('\s+', $1));
1522 $arg =~ s/\s*\[/\[/g; !! 1410 push(@first_arg, $2);
1523 !! 1411 } else {
1524 my @args = split('\s*,\s*', $arg) !! 1412 @first_arg = split('\s+', shift @args);
1525 if ($args[0] =~ m/\*/) { !! 1413 }
1526 $args[0] =~ s/(\*+)\s*/ $1/; !! 1414
1527 } !! 1415 unshift(@args, pop @first_arg);
1528 !! 1416 $type = join " ", @first_arg;
1529 my @first_arg; !! 1417
1530 if ($args[0] =~ /^(.*\s+)(.*?\[.* !! 1418 foreach $param (@args) {
1531 shift @args; !! 1419 if ($param =~ m/^(\*+)\s*(.*)/) {
1532 push(@first_arg, split('\s+', !! 1420 save_struct_actual($2);
1533 push(@first_arg, $2); !! 1421 push_parameter($2, "$type $1", $file, $declaration_name);
1534 } else { !! 1422 }
1535 @first_arg = split('\s+', shi !! 1423 elsif ($param =~ m/(.*?):(\d+)/) {
1536 } !! 1424 if ($type ne "") { # skip unnamed bit-fields
1537 !! 1425 save_struct_actual($1);
1538 unshift(@args, pop @first_arg); !! 1426 push_parameter($1, "$type:$2", $file, $declaration_name)
1539 $type = join " ", @first_arg; !! 1427 }
1540 !! 1428 }
1541 foreach $param (@args) { !! 1429 else {
1542 if ($param =~ m/^(\*+)\s*(.*) !! 1430 save_struct_actual($param);
1543 save_struct_actual($2); !! 1431 push_parameter($param, $type, $file, $declaration_name);
1544 !! 1432 }
1545 push_parameter($2, "$type !! 1433 }
1546 } elsif ($param =~ m/(.*?):(\ !! 1434 }
1547 if ($type ne "") { # skip !! 1435 }
1548 save_struct_actual($1 !! 1436 }
1549 push_parameter($1, "$ !! 1437
1550 } !! 1438 sub push_parameter($$$$) {
1551 } else { !! 1439 my $param = shift;
1552 save_struct_actual($param !! 1440 my $type = shift;
1553 push_parameter($param, $t !! 1441 my $file = shift;
1554 } !! 1442 my $declaration_name = shift;
1555 } !! 1443
1556 } !! 1444 if (($anon_struct_union == 1) && ($type eq "") &&
1557 } !! 1445 ($param eq "}")) {
1558 } !! 1446 return; # ignore the ending }; from anon. struct/union
1559 !! 1447 }
1560 sub push_parameter($$$$$) { !! 1448
1561 my $param = shift; !! 1449 $anon_struct_union = 0;
1562 my $type = shift; !! 1450 $param =~ s/[\[\)].*//;
1563 my $org_arg = shift; !! 1451
1564 my $file = shift; !! 1452 if ($type eq "" && $param =~ /\.\.\.$/)
1565 my $declaration_name = shift; !! 1453 {
1566 !! 1454 if (!$param =~ /\w\.\.\.$/) {
1567 if (($anon_struct_union == 1) && ($type e !! 1455 # handles unnamed variable parameters
1568 ($param eq "}")) { !! 1456 $param = "...";
1569 return; # ignore the ending }; !! 1457 }
1570 } !! 1458 elsif ($param =~ /\w\.\.\.$/) {
1571 !! 1459 # for named variable parameters of the form `x...`, remove the dots
1572 $anon_struct_union = 0; !! 1460 $param =~ s/\.\.\.$//;
1573 $param =~ s/[\[\)].*//; !! 1461 }
1574 !! 1462 if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
1575 if ($type eq "" && $param =~ /\.\.\.$/) !! 1463 $parameterdescs{$param} = "variable arguments";
1576 { !! 1464 }
1577 if (!$param =~ /\w\.\.\.$/) { !! 1465 }
1578 # handles unnamed variable parame !! 1466 elsif ($type eq "" && ($param eq "" or $param eq "void"))
1579 $param = "..."; !! 1467 {
1580 } elsif ($param =~ /\w\.\.\.$/) { !! 1468 $param="void";
1581 # for named variable parameters o !! 1469 $parameterdescs{void} = "no arguments";
1582 $param =~ s/\.\.\.$//; !! 1470 }
1583 } !! 1471 elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
1584 if (!defined $parameterdescs{$param} !! 1472 # handle unnamed (anonymous) union or struct:
1585 $parameterdescs{$param} = "variab !! 1473 {
1586 } !! 1474 $type = $param;
1587 } !! 1475 $param = "{unnamed_" . $param . "}";
1588 elsif ($type eq "" && ($param eq "" or $p !! 1476 $parameterdescs{$param} = "anonymous\n";
1589 { !! 1477 $anon_struct_union = 1;
1590 $param="void"; !! 1478 }
1591 $parameterdescs{void} = "no arguments !! 1479
1592 } !! 1480 # warn if parameter has no description
1593 elsif ($type eq "" && ($param eq "struct" !! 1481 # (but ignore ones starting with # as these are not parameters
1594 # handle unnamed (anonymous) union or str !! 1482 # but inline preprocessor statements);
1595 { !! 1483 # Note: It will also ignore void params and unnamed structs/unions
1596 $type = $param; !! 1484 if (!defined $parameterdescs{$param} && $param !~ /^#/) {
1597 $param = "{unnamed_" . $param . "}"; !! 1485 $parameterdescs{$param} = $undescribed;
1598 $parameterdescs{$param} = "anonymous\ !! 1486
1599 $anon_struct_union = 1; !! 1487 if (show_warnings($type, $declaration_name) && $param !~ /\./) {
1600 } !! 1488 print STDERR
1601 elsif ($param =~ "__cacheline_group" ) !! 1489 "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
1602 # handle cache group enforcing variables: !! 1490 ++$warnings;
1603 { !! 1491 }
1604 return; # ignore __cacheline_group_be !! 1492 }
1605 } !! 1493
1606 !! 1494 # strip spaces from $param so that it is one continuous string
1607 # warn if parameter has no description !! 1495 # on @parameterlist;
1608 # (but ignore ones starting with # as the !! 1496 # this fixes a problem where check_sections() cannot find
1609 # but inline preprocessor statements); !! 1497 # a parameter like "addr[6 + 2]" because it actually appears
1610 # Note: It will also ignore void params a !! 1498 # as "addr[6", "+", "2]" on the parameter list;
1611 if (!defined $parameterdescs{$param} && $ !! 1499 # but it's better to maintain the param string unchanged for output,
1612 $parameterdescs{$param} = $undescribe !! 1500 # so just weaken the string compare in check_sections() to ignore
1613 !! 1501 # "[blah" in a parameter string;
1614 if (show_warnings($type, $declaration !! 1502 ###$param =~ s/\s*//g;
1615 emit_warning("${file}:$.", "Funct !! 1503 push @parameterlist, $param;
1616 } !! 1504 $type =~ s/\s\s+/ /g;
1617 } !! 1505 $parametertypes{$param} = $type;
1618 <<
1619 # strip spaces from $param so that it is <<
1620 # on @parameterlist; <<
1621 # this fixes a problem where check_sectio <<
1622 # a parameter like "addr[6 + 2]" because <<
1623 # as "addr[6", "+", "2]" on the parameter <<
1624 # but it's better to maintain the param s <<
1625 # so just weaken the string compare in ch <<
1626 # "[blah" in a parameter string; <<
1627 ###$param =~ s/\s*//g; <<
1628 push @parameterlist, $param; <<
1629 $org_arg =~ s/\s\s+/ /g; <<
1630 $parametertypes{$param} = $org_arg; <<
1631 } 1506 }
1632 1507
1633 sub check_sections($$$$$) { 1508 sub check_sections($$$$$) {
1634 my ($file, $decl_name, $decl_type, $sectc !! 1509 my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck) = @_;
1635 my @sects = split ' ', $sectcheck; !! 1510 my @sects = split ' ', $sectcheck;
1636 my @prms = split ' ', $prmscheck; !! 1511 my @prms = split ' ', $prmscheck;
1637 my $err; !! 1512 my $err;
1638 my ($px, $sx); !! 1513 my ($px, $sx);
1639 my $prm_clean; # strip trailing "[ !! 1514 my $prm_clean; # strip trailing "[array size]" and/or beginning "*"
1640 !! 1515
1641 foreach $sx (0 .. $#sects) { !! 1516 foreach $sx (0 .. $#sects) {
1642 $err = 1; !! 1517 $err = 1;
1643 foreach $px (0 .. $#prms) { !! 1518 foreach $px (0 .. $#prms) {
1644 $prm_clean = $prms[$px]; !! 1519 $prm_clean = $prms[$px];
1645 $prm_clean =~ s/\[.*\]//; !! 1520 $prm_clean =~ s/\[.*\]//;
1646 $prm_clean =~ s/$attribute//i; !! 1521 $prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
1647 # ignore array size in a paramete !! 1522 # ignore array size in a parameter string;
1648 # however, the original param str !! 1523 # however, the original param string may contain
1649 # spaces, e.g.: addr[6 + 2] !! 1524 # spaces, e.g.: addr[6 + 2]
1650 # and this appears in @prms as "a !! 1525 # and this appears in @prms as "addr[6" since the
1651 # parameter list is split at spac !! 1526 # parameter list is split at spaces;
1652 # hence just ignore "[..." for th !! 1527 # hence just ignore "[..." for the sections check;
1653 $prm_clean =~ s/\[.*//; !! 1528 $prm_clean =~ s/\[.*//;
1654 !! 1529
1655 ##$prm_clean =~ s/^\**//; !! 1530 ##$prm_clean =~ s/^\**//;
1656 if ($prm_clean eq $sects[$sx]) { !! 1531 if ($prm_clean eq $sects[$sx]) {
1657 $err = 0; !! 1532 $err = 0;
1658 last; !! 1533 last;
1659 } !! 1534 }
1660 } !! 1535 }
1661 if ($err) { !! 1536 if ($err) {
1662 if ($decl_type eq "function") { !! 1537 if ($decl_type eq "function") {
1663 emit_warning("${file}:$.", !! 1538 print STDERR "${file}:$.: warning: " .
1664 "Excess function paramete !! 1539 "Excess function parameter " .
1665 "'$sects[$sx]' " . !! 1540 "'$sects[$sx]' " .
1666 "description in '$decl_na !! 1541 "description in '$decl_name'\n";
1667 } elsif (($decl_type eq "struct") !! 1542 ++$warnings;
1668 ($decl_type eq "uni !! 1543 }
1669 emit_warning("${file}:$.", !! 1544 }
1670 "Excess $decl_type member !! 1545 }
1671 "'$sects[$sx]' " . <<
1672 "description in '$decl_na <<
1673 } <<
1674 } <<
1675 } <<
1676 } 1546 }
1677 1547
1678 ## 1548 ##
1679 # Checks the section describing the return va 1549 # Checks the section describing the return value of a function.
1680 sub check_return_section { 1550 sub check_return_section {
1681 my $file = shift; !! 1551 my $file = shift;
1682 my $declaration_name = shift; !! 1552 my $declaration_name = shift;
1683 my $return_type = shift; !! 1553 my $return_type = shift;
1684 !! 1554
1685 # Ignore an empty return type (It's a mac !! 1555 # Ignore an empty return type (It's a macro)
1686 # Ignore functions with a "void" return t !! 1556 # Ignore functions with a "void" return type. (But don't ignore "void *")
1687 if (($return_type eq "") || ($return_type !! 1557 if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
1688 return; !! 1558 return;
1689 } !! 1559 }
1690 !! 1560
1691 if (!defined($sections{$section_return}) !! 1561 if (!defined($sections{$section_return}) ||
1692 $sections{$section_return} eq "") !! 1562 $sections{$section_return} eq "") {
1693 { !! 1563 print STDERR "${file}:$.: warning: " .
1694 emit_warning("${file}:$.", !! 1564 "No description found for return value of " .
1695 "No description found fo !! 1565 "'$declaration_name'\n";
1696 "'$declaration_name'\n") !! 1566 ++$warnings;
1697 } !! 1567 }
1698 } 1568 }
1699 1569
1700 ## 1570 ##
1701 # takes a function prototype and the name of 1571 # takes a function prototype and the name of the current file being
1702 # processed and spits out all the details sto 1572 # processed and spits out all the details stored in the global
1703 # arrays/hashes. 1573 # arrays/hashes.
1704 sub dump_function($$) { 1574 sub dump_function($$) {
1705 my $prototype = shift; 1575 my $prototype = shift;
1706 my $file = shift; 1576 my $file = shift;
1707 my $noret = 0; 1577 my $noret = 0;
1708 1578
1709 print_lineno($new_start_line); <<
1710 <<
1711 $prototype =~ s/^static +//; 1579 $prototype =~ s/^static +//;
1712 $prototype =~ s/^extern +//; 1580 $prototype =~ s/^extern +//;
1713 $prototype =~ s/^asmlinkage +//; 1581 $prototype =~ s/^asmlinkage +//;
1714 $prototype =~ s/^inline +//; 1582 $prototype =~ s/^inline +//;
1715 $prototype =~ s/^__inline__ +//; 1583 $prototype =~ s/^__inline__ +//;
1716 $prototype =~ s/^__inline +//; 1584 $prototype =~ s/^__inline +//;
1717 $prototype =~ s/^__always_inline +//; 1585 $prototype =~ s/^__always_inline +//;
1718 $prototype =~ s/^noinline +//; 1586 $prototype =~ s/^noinline +//;
1719 $prototype =~ s/^__FORTIFY_INLINE +//; <<
1720 $prototype =~ s/__init +//; 1587 $prototype =~ s/__init +//;
1721 $prototype =~ s/__init_or_module +//; 1588 $prototype =~ s/__init_or_module +//;
1722 $prototype =~ s/__deprecated +//; <<
1723 $prototype =~ s/__flatten +//; <<
1724 $prototype =~ s/__meminit +//; 1589 $prototype =~ s/__meminit +//;
1725 $prototype =~ s/__must_check +//; 1590 $prototype =~ s/__must_check +//;
1726 $prototype =~ s/__weak +//; 1591 $prototype =~ s/__weak +//;
1727 $prototype =~ s/__sched +//; 1592 $prototype =~ s/__sched +//;
1728 $prototype =~ s/_noprof//; <<
1729 $prototype =~ s/__printf\s*\(\s*\d*\s*,\s 1593 $prototype =~ s/__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +//;
1730 $prototype =~ s/__(?:re)?alloc_size\s*\(\ <<
1731 $prototype =~ s/__diagnose_as\s*\(\s*\S+\ <<
1732 $prototype =~ s/DECL_BUCKET_PARAMS\s*\(\s <<
1733 my $define = $prototype =~ s/^#\s*define\ 1594 my $define = $prototype =~ s/^#\s*define\s+//; #ak added
1734 $prototype =~ s/__attribute_const__ +//; <<
1735 $prototype =~ s/__attribute__\s*\(\( 1595 $prototype =~ s/__attribute__\s*\(\(
1736 (?: 1596 (?:
1737 [\w\s]++ # attribut 1597 [\w\s]++ # attribute name
1738 (?:\([^)]*+\))? # attribut 1598 (?:\([^)]*+\))? # attribute arguments
1739 \s*+,? # optional 1599 \s*+,? # optional comma at the end
1740 )+ 1600 )+
1741 \)\)\s+//x; 1601 \)\)\s+//x;
1742 1602
1743 # Yes, this truly is vile. We are lookin 1603 # Yes, this truly is vile. We are looking for:
1744 # 1. Return type (may be nothing if we're 1604 # 1. Return type (may be nothing if we're looking at a macro)
1745 # 2. Function name 1605 # 2. Function name
1746 # 3. Function parameters. 1606 # 3. Function parameters.
1747 # 1607 #
1748 # All the while we have to watch out for 1608 # All the while we have to watch out for function pointer parameters
1749 # (which IIRC is what the two sections ar 1609 # (which IIRC is what the two sections are for), C types (these
1750 # regexps don't even start to express all 1610 # regexps don't even start to express all the possibilities), and
1751 # so on. 1611 # so on.
1752 # 1612 #
1753 # If you mess with these regexps, it's a 1613 # If you mess with these regexps, it's a good idea to check that
1754 # the following functions' documentation 1614 # the following functions' documentation still comes out right:
1755 # - parport_register_device (function poi 1615 # - parport_register_device (function pointer parameters)
1756 # - atomic_set (macro) 1616 # - atomic_set (macro)
1757 # - pci_match_device, __copy_to_user (lon 1617 # - pci_match_device, __copy_to_user (long return type)
1758 my $name = qr{[a-zA-Z0-9_~:]+}; <<
1759 my $prototype_end1 = qr{[^\(]*}; <<
1760 my $prototype_end2 = qr{[^\{]*}; <<
1761 my $prototype_end = qr{\(($prototype_end1 <<
1762 my $type1 = qr{[\w\s]+}; <<
1763 my $type2 = qr{$type1\*+}; <<
1764 1618
1765 if ($define && $prototype =~ m/^()($name) !! 1619 if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) {
1766 # This is an object-like macro, it ha 1620 # This is an object-like macro, it has no return type and no parameter
1767 # list. 1621 # list.
1768 # Function-like macros are not allowe 1622 # Function-like macros are not allowed to have spaces between
1769 # declaration_name and opening parent 1623 # declaration_name and opening parenthesis (notice the \s+).
1770 $return_type = $1; 1624 $return_type = $1;
1771 $declaration_name = $2; 1625 $declaration_name = $2;
1772 $noret = 1; 1626 $noret = 1;
1773 } elsif ($prototype =~ m/^()($name)\s*$pr !! 1627 } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1774 $prototype =~ m/^($type1)\s+($name)\s !! 1628 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1775 $prototype =~ m/^($type2+)\s*($name)\ !! 1629 $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1776 $return_type = $1; !! 1630 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1777 $declaration_name = $2; !! 1631 $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1778 my $args = $3; !! 1632 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
>> 1633 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
>> 1634 $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 1635 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 1636 $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 1637 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 1638 $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 1639 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 1640 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 1641 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 1642 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 1643 $prototype =~ m/^(\w+\s+\w+\s*\*+\s*\w+\s*\*+\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) {
>> 1644 $return_type = $1;
>> 1645 $declaration_name = $2;
>> 1646 my $args = $3;
1779 1647
1780 create_parameterlist($args, ',', $fil !! 1648 create_parameterlist($args, ',', $file, $declaration_name);
1781 } else { 1649 } else {
1782 emit_warning("${file}:$.", "cannot un !! 1650 print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
1783 return; !! 1651 return;
1784 } <<
1785 <<
1786 if ($identifier ne $declaration_name) { <<
1787 emit_warning("${file}:$.", "expecting <<
1788 return; <<
1789 } 1652 }
1790 1653
1791 my $prms = join " ", @parameterlist; !! 1654 my $prms = join " ", @parameterlist;
1792 check_sections($file, $declaration_name, !! 1655 check_sections($file, $declaration_name, "function", $sectcheck, $prms);
1793 1656
1794 # This check emits a lot of warnings at t !! 1657 # This check emits a lot of warnings at the moment, because many
1795 # functions don't have a 'Return' doc sec !! 1658 # functions don't have a 'Return' doc section. So until the number
1796 # of warnings goes sufficiently down, the !! 1659 # of warnings goes sufficiently down, the check is only performed in
1797 # -Wreturn mode. !! 1660 # verbose mode.
1798 # TODO: always perform the check. !! 1661 # TODO: always perform the check.
1799 if ($Wreturn && !$noret) { !! 1662 if ($verbose && !$noret) {
1800 check_return_section($file, $declarat !! 1663 check_return_section($file, $declaration_name, $return_type);
1801 } !! 1664 }
1802 !! 1665
1803 # The function parser can be called with !! 1666 output_declaration($declaration_name,
1804 # Handle it. !! 1667 'function',
1805 if ($return_type =~ /typedef/) { !! 1668 {'function' => $declaration_name,
1806 output_declaration($declaration_name, !! 1669 'module' => $modulename,
1807 'function', !! 1670 'functiontype' => $return_type,
1808 {'function' => $de !! 1671 'parameterlist' => \@parameterlist,
1809 'typedef' => 1, !! 1672 'parameterdescs' => \%parameterdescs,
1810 'module' => $modu !! 1673 'parametertypes' => \%parametertypes,
1811 'functiontype' => !! 1674 'sectionlist' => \@sectionlist,
1812 'parameterlist' = !! 1675 'sections' => \%sections,
1813 'parameterdescs' !! 1676 'purpose' => $declaration_purpose
1814 'parametertypes' !! 1677 });
1815 'sectionlist' => <<
1816 'sections' => \%s <<
1817 'purpose' => $dec <<
1818 }); <<
1819 } else { <<
1820 output_declaration($declaration_name, <<
1821 'function', <<
1822 {'function' => $de <<
1823 'module' => $modu <<
1824 'functiontype' => <<
1825 'parameterlist' = <<
1826 'parameterdescs' <<
1827 'parametertypes' <<
1828 'sectionlist' => <<
1829 'sections' => \%s <<
1830 'purpose' => $dec <<
1831 }); <<
1832 } <<
1833 } 1678 }
1834 1679
1835 sub reset_state { 1680 sub reset_state {
1836 $function = ""; 1681 $function = "";
1837 %parameterdescs = (); 1682 %parameterdescs = ();
1838 %parametertypes = (); 1683 %parametertypes = ();
1839 @parameterlist = (); 1684 @parameterlist = ();
1840 %sections = (); 1685 %sections = ();
1841 @sectionlist = (); 1686 @sectionlist = ();
1842 $sectcheck = ""; 1687 $sectcheck = "";
1843 $struct_actual = ""; 1688 $struct_actual = "";
1844 $prototype = ""; 1689 $prototype = "";
1845 1690
1846 $state = STATE_NORMAL; 1691 $state = STATE_NORMAL;
1847 $inline_doc_state = STATE_INLINE_NA; 1692 $inline_doc_state = STATE_INLINE_NA;
1848 } 1693 }
1849 1694
1850 sub tracepoint_munge($) { 1695 sub tracepoint_munge($) {
1851 my $file = shift; !! 1696 my $file = shift;
1852 my $tracepointname = 0; !! 1697 my $tracepointname = 0;
1853 my $tracepointargs = 0; !! 1698 my $tracepointargs = 0;
1854 !! 1699
1855 if ($prototype =~ m/TRACE_EVENT\((.*?),/) !! 1700 if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
1856 $tracepointname = $1; !! 1701 $tracepointname = $1;
1857 } !! 1702 }
1858 if ($prototype =~ m/DEFINE_SINGLE_EVENT\( !! 1703 if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
1859 $tracepointname = $1; !! 1704 $tracepointname = $1;
1860 } !! 1705 }
1861 if ($prototype =~ m/DEFINE_EVENT\((.*?),( !! 1706 if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
1862 $tracepointname = $2; !! 1707 $tracepointname = $2;
1863 } !! 1708 }
1864 $tracepointname =~ s/^\s+//; #strip leadi !! 1709 $tracepointname =~ s/^\s+//; #strip leading whitespace
1865 if ($prototype =~ m/TP_PROTO\((.*?)\)/) { !! 1710 if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
1866 $tracepointargs = $1; !! 1711 $tracepointargs = $1;
1867 } !! 1712 }
1868 if (($tracepointname eq 0) || ($tracepoin !! 1713 if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
1869 emit_warning("${file}:$.", "Unrecogni !! 1714 print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
1870 "$prototype\n"); !! 1715 "$prototype\n";
1871 } else { !! 1716 } else {
1872 $prototype = "static inline void trac !! 1717 $prototype = "static inline void trace_$tracepointname($tracepointargs)";
1873 $identifier = "trace_$identifier"; !! 1718 }
1874 } <<
1875 } 1719 }
1876 1720
1877 sub syscall_munge() { 1721 sub syscall_munge() {
1878 my $void = 0; !! 1722 my $void = 0;
1879 <<
1880 $prototype =~ s@[\r\n]+@ @gos; # strip ne <<
1881 ## if ($prototype =~ m/SYSCALL_DEFINE0\s*\ <<
1882 if ($prototype =~ m/SYSCALL_DEFINE0/) { <<
1883 $void = 1; <<
1884 ## $prototype = "long sys_$1(void)"; <<
1885 } <<
1886 <<
1887 $prototype =~ s/SYSCALL_DEFINE.*\(/long s <<
1888 if ($prototype =~ m/long (sys_.*?),/) { <<
1889 $prototype =~ s/,/\(/; <<
1890 } elsif ($void) { <<
1891 $prototype =~ s/\)/\(void\)/; <<
1892 } <<
1893 1723
1894 # now delete all of the odd-number commas !! 1724 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/CR's
1895 # so that arg types & arg names don't hav !! 1725 ## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
1896 my $count = 0; !! 1726 if ($prototype =~ m/SYSCALL_DEFINE0/) {
1897 my $len = length($prototype); !! 1727 $void = 1;
1898 if ($void) { !! 1728 ## $prototype = "long sys_$1(void)";
1899 $len = 0; # skip the for-loop !! 1729 }
1900 } !! 1730
1901 for (my $ix = 0; $ix < $len; $ix++) { !! 1731 $prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
1902 if (substr($prototype, $ix, 1) eq ',' !! 1732 if ($prototype =~ m/long (sys_.*?),/) {
1903 $count++; !! 1733 $prototype =~ s/,/\(/;
1904 if ($count % 2 == 1) { !! 1734 } elsif ($void) {
1905 substr($prototype, $ix, 1) = !! 1735 $prototype =~ s/\)/\(void\)/;
1906 } !! 1736 }
1907 } !! 1737
1908 } !! 1738 # now delete all of the odd-number commas in $prototype
>> 1739 # so that arg types & arg names don't have a comma between them
>> 1740 my $count = 0;
>> 1741 my $len = length($prototype);
>> 1742 if ($void) {
>> 1743 $len = 0; # skip the for-loop
>> 1744 }
>> 1745 for (my $ix = 0; $ix < $len; $ix++) {
>> 1746 if (substr($prototype, $ix, 1) eq ',') {
>> 1747 $count++;
>> 1748 if ($count % 2 == 1) {
>> 1749 substr($prototype, $ix, 1) = ' ';
>> 1750 }
>> 1751 }
>> 1752 }
1909 } 1753 }
1910 1754
1911 sub process_proto_function($$) { 1755 sub process_proto_function($$) {
1912 my $x = shift; 1756 my $x = shift;
1913 my $file = shift; 1757 my $file = shift;
1914 1758
1915 $x =~ s@\/\/.*$@@gos; # strip C99-style c 1759 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1916 1760
1917 if ($x =~ /^#/ && $x !~ /^#\s*define/) { !! 1761 if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
1918 # do nothing !! 1762 # do nothing
1919 } elsif ($x =~ /([^\{]*)/) { !! 1763 }
1920 $prototype .= $1; !! 1764 elsif ($x =~ /([^\{]*)/) {
>> 1765 $prototype .= $1;
1921 } 1766 }
1922 1767
1923 if (($x =~ /\{/) || ($x =~ /\#\s*define/) 1768 if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
1924 $prototype =~ s@/\*.*?\*/@@gos; !! 1769 $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
1925 $prototype =~ s@[\r\n]+@ @gos; # stri !! 1770 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1926 $prototype =~ s@^\s+@@gos; # strip le !! 1771 $prototype =~ s@^\s+@@gos; # strip leading spaces
1927 !! 1772 if ($prototype =~ /SYSCALL_DEFINE/) {
1928 # Handle prototypes for function poin !! 1773 syscall_munge();
1929 # int (*pcs_config)(struct foo) !! 1774 }
1930 $prototype =~ s@^(\S+\s+)\(\s*\*(\S+) !! 1775 if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
1931 !! 1776 $prototype =~ /DEFINE_SINGLE_EVENT/)
1932 if ($prototype =~ /SYSCALL_DEFINE/) { !! 1777 {
1933 syscall_munge(); !! 1778 tracepoint_munge($file);
1934 } !! 1779 }
1935 if ($prototype =~ /TRACE_EVENT/ || $p !! 1780 dump_function($prototype, $file);
1936 $prototype =~ /DEFINE_SINGLE_EVEN !! 1781 reset_state();
1937 { <<
1938 tracepoint_munge($file); <<
1939 } <<
1940 dump_function($prototype, $file); <<
1941 reset_state(); <<
1942 } 1782 }
1943 } 1783 }
1944 1784
1945 sub process_proto_type($$) { 1785 sub process_proto_type($$) {
1946 my $x = shift; 1786 my $x = shift;
1947 my $file = shift; 1787 my $file = shift;
1948 1788
1949 $x =~ s@[\r\n]+@ @gos; # strip newlines/c 1789 $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1950 $x =~ s@^\s+@@gos; # strip leading spaces 1790 $x =~ s@^\s+@@gos; # strip leading spaces
1951 $x =~ s@\s+$@@gos; # strip trailing space 1791 $x =~ s@\s+$@@gos; # strip trailing spaces
1952 $x =~ s@\/\/.*$@@gos; # strip C99-style c 1792 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1953 1793
1954 if ($x =~ /^#/) { 1794 if ($x =~ /^#/) {
1955 # To distinguish preprocessor directi !! 1795 # To distinguish preprocessor directive from regular declaration later.
1956 $x .= ";"; !! 1796 $x .= ";";
1957 } 1797 }
1958 1798
1959 while (1) { 1799 while (1) {
1960 if ( $x =~ /([^\{\};]*)([\{\};])(.*)/ !! 1800 if ( $x =~ /([^\{\};]*)([\{\};])(.*)/ ) {
1961 if( length $prototype ) { 1801 if( length $prototype ) {
1962 $prototype .= " " 1802 $prototype .= " "
1963 } 1803 }
1964 $prototype .= $1 . $2; !! 1804 $prototype .= $1 . $2;
1965 ($2 eq '{') && $brcount++; !! 1805 ($2 eq '{') && $brcount++;
1966 ($2 eq '}') && $brcount--; !! 1806 ($2 eq '}') && $brcount--;
1967 if (($2 eq ';') && ($brcount == 0 !! 1807 if (($2 eq ';') && ($brcount == 0)) {
1968 dump_declaration($prototype, !! 1808 dump_declaration($prototype, $file);
1969 reset_state(); !! 1809 reset_state();
1970 last; !! 1810 last;
1971 } !! 1811 }
1972 $x = $3; !! 1812 $x = $3;
1973 } else { !! 1813 } else {
1974 $prototype .= $x; !! 1814 $prototype .= $x;
1975 last; !! 1815 last;
1976 } !! 1816 }
1977 } 1817 }
1978 } 1818 }
1979 1819
1980 1820
1981 sub map_filename($) { 1821 sub map_filename($) {
1982 my $file; 1822 my $file;
1983 my ($orig_file) = @_; 1823 my ($orig_file) = @_;
1984 1824
1985 if (defined($ENV{'SRCTREE'})) { 1825 if (defined($ENV{'SRCTREE'})) {
1986 $file = "$ENV{'SRCTREE'}" . "/" . $or !! 1826 $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
1987 } else { 1827 } else {
1988 $file = $orig_file; !! 1828 $file = $orig_file;
1989 } 1829 }
1990 1830
1991 if (defined($source_map{$file})) { 1831 if (defined($source_map{$file})) {
1992 $file = $source_map{$file}; !! 1832 $file = $source_map{$file};
1993 } 1833 }
1994 1834
1995 return $file; 1835 return $file;
1996 } 1836 }
1997 1837
1998 sub process_export_file($) { 1838 sub process_export_file($) {
1999 my ($orig_file) = @_; 1839 my ($orig_file) = @_;
2000 my $file = map_filename($orig_file); 1840 my $file = map_filename($orig_file);
2001 1841
2002 if (!open(IN,"<$file")) { 1842 if (!open(IN,"<$file")) {
2003 print STDERR "Error: Cannot open file !! 1843 print STDERR "Error: Cannot open file $file\n";
2004 ++$errors; !! 1844 ++$errors;
2005 return; !! 1845 return;
2006 } 1846 }
2007 1847
2008 while (<IN>) { 1848 while (<IN>) {
2009 if (/$export_symbol/) { !! 1849 if (/$export_symbol/) {
2010 next if (defined($nosymbol_table{ !! 1850 $function_table{$2} = 1;
2011 $function_table{$2} = 1; !! 1851 }
2012 } <<
2013 if (/$export_symbol_ns/) { <<
2014 next if (defined($nosymbol_table{ <<
2015 $function_table{$2} = 1; <<
2016 } <<
2017 } 1852 }
2018 1853
2019 close(IN); 1854 close(IN);
2020 } 1855 }
2021 1856
2022 # 1857 #
2023 # Parsers for the various processing states. 1858 # Parsers for the various processing states.
2024 # 1859 #
2025 # STATE_NORMAL: looking for the /** to begin 1860 # STATE_NORMAL: looking for the /** to begin everything.
2026 # 1861 #
2027 sub process_normal() { 1862 sub process_normal() {
2028 if (/$doc_start/o) { 1863 if (/$doc_start/o) {
2029 $state = STATE_NAME; # next li !! 1864 $state = STATE_NAME; # next line is always the function name
2030 $in_doc_sect = 0; !! 1865 $in_doc_sect = 0;
2031 $declaration_start_line = $. + 1; !! 1866 $declaration_start_line = $. + 1;
2032 } 1867 }
2033 } 1868 }
2034 1869
2035 # 1870 #
2036 # STATE_NAME: Looking for the "name - descrip 1871 # STATE_NAME: Looking for the "name - description" line
2037 # 1872 #
2038 sub process_name($$) { 1873 sub process_name($$) {
2039 my $file = shift; 1874 my $file = shift;
>> 1875 my $identifier;
2040 my $descr; 1876 my $descr;
2041 1877
2042 if (/$doc_block/o) { 1878 if (/$doc_block/o) {
2043 $state = STATE_DOCBLOCK; !! 1879 $state = STATE_DOCBLOCK;
2044 $contents = ""; !! 1880 $contents = "";
2045 $new_start_line = $.; !! 1881 $new_start_line = $. + 1;
2046 !! 1882
2047 if ( $1 eq "" ) { !! 1883 if ( $1 eq "" ) {
2048 $section = $section_intro; !! 1884 $section = $section_intro;
2049 } else { !! 1885 } else {
2050 $section = $1; !! 1886 $section = $1;
2051 } !! 1887 }
2052 } elsif (/$doc_decl/o) { !! 1888 }
2053 $identifier = $1; !! 1889 elsif (/$doc_decl/o) {
2054 my $is_kernel_comment = 0; !! 1890 $identifier = $1;
2055 my $decl_start = qr{$doc_com}; !! 1891 if (/\s*([\w\s]+?)(\(\))?\s*-/) {
2056 # test for pointer declaration type, !! 1892 $identifier = $1;
2057 my $fn_type = qr{\w+\s*\*\s*}; !! 1893 }
2058 my $parenthesis = qr{\(\w*\)}; !! 1894
2059 my $decl_end = qr{[-:].*}; !! 1895 $state = STATE_BODY;
2060 if (/^$decl_start([\w\s]+?)$parenthes !! 1896 # if there's no @param blocks need to set up default section
2061 $identifier = $1; !! 1897 # here
2062 } !! 1898 $contents = "";
2063 if ($identifier =~ m/^(struct|union|e !! 1899 $section = $section_default;
2064 $decl_type = $1; !! 1900 $new_start_line = $. + 1;
2065 $identifier = $2; !! 1901 if (/-(.*)/) {
2066 $is_kernel_comment = 1; !! 1902 # strip leading/trailing/multiple spaces
2067 } !! 1903 $descr= $1;
2068 # Look for foo() or static void foo() !! 1904 $descr =~ s/^\s*//;
2069 # identifier !! 1905 $descr =~ s/\s*$//;
2070 elsif (/^$decl_start$fn_type?(\w+)\s* !! 1906 $descr =~ s/\s+/ /g;
2071 /^$decl_start$fn_type?(\w+.*)$par !! 1907 $declaration_purpose = $descr;
2072 $identifier = $1; !! 1908 $state = STATE_BODY_MAYBE;
2073 $decl_type = 'function'; !! 1909 } else {
2074 $identifier =~ s/^define\s+//; !! 1910 $declaration_purpose = "";
2075 $is_kernel_comment = 1; !! 1911 }
2076 } !! 1912
2077 $identifier =~ s/\s+$//; !! 1913 if (($declaration_purpose eq "") && $verbose) {
2078 !! 1914 print STDERR "${file}:$.: warning: missing initial short description on line:\n";
2079 $state = STATE_BODY; !! 1915 print STDERR $_;
2080 # if there's no @param blocks need to !! 1916 ++$warnings;
2081 # here !! 1917 }
2082 $contents = ""; !! 1918
2083 $section = $section_default; !! 1919 if ($identifier =~ m/^struct\b/) {
2084 $new_start_line = $. + 1; !! 1920 $decl_type = 'struct';
2085 if (/[-:](.*)/) { !! 1921 } elsif ($identifier =~ m/^union\b/) {
2086 # strip leading/trailing/multiple !! 1922 $decl_type = 'union';
2087 $descr= $1; !! 1923 } elsif ($identifier =~ m/^enum\b/) {
2088 $descr =~ s/^\s*//; !! 1924 $decl_type = 'enum';
2089 $descr =~ s/\s*$//; !! 1925 } elsif ($identifier =~ m/^typedef\b/) {
2090 $descr =~ s/\s+/ /g; !! 1926 $decl_type = 'typedef';
2091 $declaration_purpose = $descr; !! 1927 } else {
2092 $state = STATE_BODY_MAYBE; !! 1928 $decl_type = 'function';
2093 } else { !! 1929 }
2094 $declaration_purpose = ""; !! 1930
2095 } !! 1931 if ($verbose) {
2096 !! 1932 print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
2097 if (!$is_kernel_comment) { !! 1933 }
2098 emit_warning("${file}:$.", "This <<
2099 $state = STATE_NORMAL; <<
2100 } <<
2101 <<
2102 if (($declaration_purpose eq "") && $ <<
2103 emit_warning("${file}:$.", "missi <<
2104 } <<
2105 <<
2106 if ($identifier eq "" && $decl_type n <<
2107 emit_warning("${file}:$.", "wrong <<
2108 $state = STATE_NORMAL; <<
2109 } <<
2110 <<
2111 if ($verbose) { <<
2112 print STDERR "${file}:$.: info: S <<
2113 } <<
2114 } else { 1934 } else {
2115 emit_warning("${file}:$.", "Cannot un !! 1935 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
2116 $state = STATE_NORMAL; !! 1936 " - I thought it was a doc line\n";
>> 1937 ++$warnings;
>> 1938 $state = STATE_NORMAL;
2117 } 1939 }
2118 } 1940 }
2119 1941
2120 1942
2121 # 1943 #
2122 # STATE_BODY and STATE_BODY_MAYBE: the bulk o 1944 # STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment.
2123 # 1945 #
2124 sub process_body($$) { 1946 sub process_body($$) {
2125 my $file = shift; 1947 my $file = shift;
2126 1948
>> 1949 # Until all named variable macro parameters are
>> 1950 # documented using the bare name (`x`) rather than with
>> 1951 # dots (`x...`), strip the dots:
>> 1952 if ($section =~ /\w\.\.\.$/) {
>> 1953 $section =~ s/\.\.\.$//;
>> 1954
>> 1955 if ($verbose) {
>> 1956 print STDERR "${file}:$.: warning: Variable macro arguments should be documented without dots\n";
>> 1957 ++$warnings;
>> 1958 }
>> 1959 }
>> 1960
2127 if ($state == STATE_BODY_WITH_BLANK_LINE 1961 if ($state == STATE_BODY_WITH_BLANK_LINE && /^\s*\*\s?\S/) {
2128 dump_section($file, $section, $conten !! 1962 dump_section($file, $section, $contents);
2129 $section = $section_default; !! 1963 $section = $section_default;
2130 $new_start_line = $.; !! 1964 $contents = "";
2131 $contents = ""; <<
2132 } 1965 }
2133 1966
2134 if (/$doc_sect/i) { # case insensitive fo 1967 if (/$doc_sect/i) { # case insensitive for supported section names
2135 $in_doc_sect = 1; !! 1968 $newsection = $1;
2136 $newsection = $1; !! 1969 $newcontents = $2;
2137 $newcontents = $2; <<
2138 <<
2139 # map the supported section names to <<
2140 if ($newsection =~ m/^description$/i) <<
2141 $newsection = $section_default; <<
2142 } elsif ($newsection =~ m/^context$/i <<
2143 $newsection = $section_context; <<
2144 } elsif ($newsection =~ m/^returns?$/ <<
2145 $newsection = $section_return; <<
2146 } elsif ($newsection =~ m/^\@return$/ <<
2147 # special: @return is a section, <<
2148 $newsection = $section_return; <<
2149 } <<
2150 1970
2151 if (($contents ne "") && ($contents n !! 1971 # map the supported section names to the canonical names
2152 if (!$in_doc_sect && $Wcontents_b !! 1972 if ($newsection =~ m/^description$/i) {
2153 emit_warning("${file}:$.", "c !! 1973 $newsection = $section_default;
2154 } !! 1974 } elsif ($newsection =~ m/^context$/i) {
2155 dump_section($file, $section, $co !! 1975 $newsection = $section_context;
2156 $section = $section_default; !! 1976 } elsif ($newsection =~ m/^returns?$/i) {
2157 } !! 1977 $newsection = $section_return;
2158 !! 1978 } elsif ($newsection =~ m/^\@return$/) {
2159 $in_doc_sect = 1; !! 1979 # special: @return is a section, not a param description
2160 $state = STATE_BODY; !! 1980 $newsection = $section_return;
2161 $contents = $newcontents; !! 1981 }
2162 $new_start_line = $.; !! 1982
2163 while (substr($contents, 0, 1) eq " " !! 1983 if (($contents ne "") && ($contents ne "\n")) {
2164 $contents = substr($contents, 1); !! 1984 if (!$in_doc_sect && $verbose) {
2165 } !! 1985 print STDERR "${file}:$.: warning: contents before sections\n";
2166 if ($contents ne "") { !! 1986 ++$warnings;
2167 $contents .= "\n"; !! 1987 }
2168 } !! 1988 dump_section($file, $section, $contents);
2169 $section = $newsection; !! 1989 $section = $section_default;
2170 $leading_space = undef; !! 1990 }
>> 1991
>> 1992 $in_doc_sect = 1;
>> 1993 $state = STATE_BODY;
>> 1994 $contents = $newcontents;
>> 1995 $new_start_line = $.;
>> 1996 while (substr($contents, 0, 1) eq " ") {
>> 1997 $contents = substr($contents, 1);
>> 1998 }
>> 1999 if ($contents ne "") {
>> 2000 $contents .= "\n";
>> 2001 }
>> 2002 $section = $newsection;
>> 2003 $leading_space = undef;
2171 } elsif (/$doc_end/) { 2004 } elsif (/$doc_end/) {
2172 if (($contents ne "") && ($contents n !! 2005 if (($contents ne "") && ($contents ne "\n")) {
2173 dump_section($file, $section, $co !! 2006 dump_section($file, $section, $contents);
2174 $section = $section_default; !! 2007 $section = $section_default;
2175 $contents = ""; !! 2008 $contents = "";
2176 } !! 2009 }
2177 # look for doc_com + <text> + doc_end !! 2010 # look for doc_com + <text> + doc_end:
2178 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\ !! 2011 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2179 emit_warning("${file}:$.", "suspi !! 2012 print STDERR "${file}:$.: warning: suspicious ending line: $_";
2180 } !! 2013 ++$warnings;
2181 !! 2014 }
2182 $prototype = ""; !! 2015
2183 $state = STATE_PROTO; !! 2016 $prototype = "";
2184 $brcount = 0; !! 2017 $state = STATE_PROTO;
2185 $new_start_line = $. + 1; !! 2018 $brcount = 0;
2186 } elsif (/$doc_content/) { 2019 } elsif (/$doc_content/) {
2187 if ($1 eq "") { !! 2020 if ($1 eq "") {
2188 if ($section eq $section_context) !! 2021 if ($section eq $section_context) {
2189 dump_section($file, $section, !! 2022 dump_section($file, $section, $contents);
2190 $section = $section_default; !! 2023 $section = $section_default;
2191 $contents = ""; !! 2024 $contents = "";
2192 $new_start_line = $.; !! 2025 $new_start_line = $.;
2193 $state = STATE_BODY; !! 2026 $state = STATE_BODY;
2194 } else { !! 2027 } else {
2195 if ($section ne $section_defa !! 2028 if ($section ne $section_default) {
2196 $state = STATE_BODY_WITH_ !! 2029 $state = STATE_BODY_WITH_BLANK_LINE;
2197 } else { !! 2030 } else {
2198 $state = STATE_BODY; !! 2031 $state = STATE_BODY;
2199 } !! 2032 }
2200 $contents .= "\n"; !! 2033 $contents .= "\n";
2201 } !! 2034 }
2202 } elsif ($state == STATE_BODY_MAYBE) !! 2035 } elsif ($state == STATE_BODY_MAYBE) {
2203 # Continued declaration purpose !! 2036 # Continued declaration purpose
2204 chomp($declaration_purpose); !! 2037 chomp($declaration_purpose);
2205 $declaration_purpose .= " " . $1; !! 2038 $declaration_purpose .= " " . $1;
2206 $declaration_purpose =~ s/\s+/ /g !! 2039 $declaration_purpose =~ s/\s+/ /g;
2207 } else { !! 2040 } else {
2208 my $cont = $1; !! 2041 my $cont = $1;
2209 if ($section =~ m/^@/ || $section !! 2042 if ($section =~ m/^@/ || $section eq $section_context) {
2210 if (!defined $leading_space) !! 2043 if (!defined $leading_space) {
2211 if ($cont =~ m/^(\s+)/) { !! 2044 if ($cont =~ m/^(\s+)/) {
2212 $leading_space = $1; !! 2045 $leading_space = $1;
2213 } else { !! 2046 } else {
2214 $leading_space = ""; !! 2047 $leading_space = "";
2215 } !! 2048 }
2216 } !! 2049 }
2217 $cont =~ s/^$leading_space//; !! 2050 $cont =~ s/^$leading_space//;
2218 } !! 2051 }
2219 $contents .= $cont . "\n"; !! 2052 $contents .= $cont . "\n";
2220 } !! 2053 }
2221 } else { 2054 } else {
2222 # i dont know - bad line? ignore. !! 2055 # i dont know - bad line? ignore.
2223 emit_warning("${file}:$.", "bad line: !! 2056 print STDERR "${file}:$.: warning: bad line: $_";
>> 2057 ++$warnings;
2224 } 2058 }
2225 } 2059 }
2226 2060
2227 2061
2228 # 2062 #
2229 # STATE_PROTO: reading a function/whatever pr 2063 # STATE_PROTO: reading a function/whatever prototype.
2230 # 2064 #
2231 sub process_proto($$) { 2065 sub process_proto($$) {
2232 my $file = shift; 2066 my $file = shift;
2233 2067
2234 if (/$doc_inline_oneline/) { 2068 if (/$doc_inline_oneline/) {
2235 $section = $1; !! 2069 $section = $1;
2236 $contents = $2; !! 2070 $contents = $2;
2237 if ($contents ne "") { !! 2071 if ($contents ne "") {
2238 $contents .= "\n"; !! 2072 $contents .= "\n";
2239 dump_section($file, $section, $co !! 2073 dump_section($file, $section, $contents);
2240 $section = $section_default; !! 2074 $section = $section_default;
2241 $contents = ""; !! 2075 $contents = "";
2242 } !! 2076 }
2243 } elsif (/$doc_inline_start/) { 2077 } elsif (/$doc_inline_start/) {
2244 $state = STATE_INLINE; !! 2078 $state = STATE_INLINE;
2245 $inline_doc_state = STATE_INLINE_NAME !! 2079 $inline_doc_state = STATE_INLINE_NAME;
2246 } elsif ($decl_type eq 'function') { 2080 } elsif ($decl_type eq 'function') {
2247 process_proto_function($_, $file); !! 2081 process_proto_function($_, $file);
2248 } else { 2082 } else {
2249 process_proto_type($_, $file); !! 2083 process_proto_type($_, $file);
2250 } 2084 }
2251 } 2085 }
2252 2086
2253 # 2087 #
2254 # STATE_DOCBLOCK: within a DOC: block. 2088 # STATE_DOCBLOCK: within a DOC: block.
2255 # 2089 #
2256 sub process_docblock($$) { 2090 sub process_docblock($$) {
2257 my $file = shift; 2091 my $file = shift;
2258 2092
2259 if (/$doc_end/) { 2093 if (/$doc_end/) {
2260 dump_doc_section($file, $section, $co !! 2094 dump_doc_section($file, $section, $contents);
2261 $section = $section_default; !! 2095 $section = $section_default;
2262 $contents = ""; !! 2096 $contents = "";
2263 $function = ""; !! 2097 $function = "";
2264 %parameterdescs = (); !! 2098 %parameterdescs = ();
2265 %parametertypes = (); !! 2099 %parametertypes = ();
2266 @parameterlist = (); !! 2100 @parameterlist = ();
2267 %sections = (); !! 2101 %sections = ();
2268 @sectionlist = (); !! 2102 @sectionlist = ();
2269 $prototype = ""; !! 2103 $prototype = "";
2270 $state = STATE_NORMAL; !! 2104 $state = STATE_NORMAL;
2271 } elsif (/$doc_content/) { 2105 } elsif (/$doc_content/) {
2272 if ( $1 eq "" ) { !! 2106 if ( $1 eq "" ) {
2273 $contents .= $blankline; !! 2107 $contents .= $blankline;
2274 } else { !! 2108 } else {
2275 $contents .= $1 . "\n"; !! 2109 $contents .= $1 . "\n";
2276 } !! 2110 }
2277 } 2111 }
2278 } 2112 }
2279 2113
2280 # 2114 #
2281 # STATE_INLINE: docbook comments within a pro 2115 # STATE_INLINE: docbook comments within a prototype.
2282 # 2116 #
2283 sub process_inline($$) { 2117 sub process_inline($$) {
2284 my $file = shift; 2118 my $file = shift;
2285 2119
2286 # First line (state 1) needs to be a @par 2120 # First line (state 1) needs to be a @parameter
2287 if ($inline_doc_state == STATE_INLINE_NAM 2121 if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
2288 $section = $1; !! 2122 $section = $1;
2289 $contents = $2; !! 2123 $contents = $2;
2290 $new_start_line = $.; !! 2124 $new_start_line = $.;
2291 if ($contents ne "") { !! 2125 if ($contents ne "") {
2292 while (substr($contents, 0, 1) eq !! 2126 while (substr($contents, 0, 1) eq " ") {
2293 $contents = substr($contents, !! 2127 $contents = substr($contents, 1);
2294 } !! 2128 }
2295 $contents .= "\n"; !! 2129 $contents .= "\n";
2296 } !! 2130 }
2297 $inline_doc_state = STATE_INLINE_TEXT !! 2131 $inline_doc_state = STATE_INLINE_TEXT;
2298 # Documentation block end */ !! 2132 # Documentation block end */
2299 } elsif (/$doc_inline_end/) { 2133 } elsif (/$doc_inline_end/) {
2300 if (($contents ne "") && ($contents n !! 2134 if (($contents ne "") && ($contents ne "\n")) {
2301 dump_section($file, $section, $co !! 2135 dump_section($file, $section, $contents);
2302 $section = $section_default; !! 2136 $section = $section_default;
2303 $contents = ""; !! 2137 $contents = "";
2304 } !! 2138 }
2305 $state = STATE_PROTO; !! 2139 $state = STATE_PROTO;
2306 $inline_doc_state = STATE_INLINE_NA; !! 2140 $inline_doc_state = STATE_INLINE_NA;
2307 # Regular text !! 2141 # Regular text
2308 } elsif (/$doc_content/) { 2142 } elsif (/$doc_content/) {
2309 if ($inline_doc_state == STATE_INLINE !! 2143 if ($inline_doc_state == STATE_INLINE_TEXT) {
2310 $contents .= $1 . "\n"; !! 2144 $contents .= $1 . "\n";
2311 # nuke leading blank lines !! 2145 # nuke leading blank lines
2312 if ($contents =~ /^\s*$/) { !! 2146 if ($contents =~ /^\s*$/) {
2313 $contents = ""; !! 2147 $contents = "";
2314 } !! 2148 }
2315 } elsif ($inline_doc_state == STATE_I !! 2149 } elsif ($inline_doc_state == STATE_INLINE_NAME) {
2316 $inline_doc_state = STATE_INLINE_ !! 2150 $inline_doc_state = STATE_INLINE_ERROR;
2317 emit_warning("${file}:$.", "Incor !! 2151 print STDERR "${file}:$.: warning: ";
2318 } !! 2152 print STDERR "Incorrect use of kernel-doc format: $_";
>> 2153 ++$warnings;
>> 2154 }
2319 } 2155 }
2320 } 2156 }
2321 2157
2322 2158
2323 sub process_file($) { 2159 sub process_file($) {
2324 my $file; 2160 my $file;
2325 my $initial_section_counter = $section_co 2161 my $initial_section_counter = $section_counter;
2326 my ($orig_file) = @_; 2162 my ($orig_file) = @_;
2327 2163
2328 $file = map_filename($orig_file); 2164 $file = map_filename($orig_file);
2329 2165
2330 if (!open(IN_FILE,"<$file")) { !! 2166 if (!open(IN,"<$file")) {
2331 print STDERR "Error: Cannot open file !! 2167 print STDERR "Error: Cannot open file $file\n";
2332 ++$errors; !! 2168 ++$errors;
2333 return; !! 2169 return;
2334 } 2170 }
2335 2171
2336 $. = 1; 2172 $. = 1;
2337 2173
2338 $section_counter = 0; 2174 $section_counter = 0;
2339 while (<IN_FILE>) { !! 2175 while (<IN>) {
2340 while (!/^ \*/ && s/\\\s*$//) { !! 2176 while (s/\\\s*$//) {
2341 $_ .= <IN_FILE>; !! 2177 $_ .= <IN>;
2342 } !! 2178 }
2343 # Replace tabs by spaces !! 2179 # Replace tabs by spaces
2344 while ($_ =~ s/\t+/' ' x (length($&) 2180 while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
2345 # Hand this line to the appropriate s !! 2181 # Hand this line to the appropriate state handler
2346 if ($state == STATE_NORMAL) { !! 2182 if ($state == STATE_NORMAL) {
2347 process_normal(); !! 2183 process_normal();
2348 } elsif ($state == STATE_NAME) { !! 2184 } elsif ($state == STATE_NAME) {
2349 process_name($file, $_); !! 2185 process_name($file, $_);
2350 } elsif ($state == STATE_BODY || $sta !! 2186 } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE ||
2351 $state == STATE_BODY_WITH_BL !! 2187 $state == STATE_BODY_WITH_BLANK_LINE) {
2352 process_body($file, $_); !! 2188 process_body($file, $_);
2353 } elsif ($state == STATE_INLINE) { # !! 2189 } elsif ($state == STATE_INLINE) { # scanning for inline parameters
2354 process_inline($file, $_); !! 2190 process_inline($file, $_);
2355 } elsif ($state == STATE_PROTO) { !! 2191 } elsif ($state == STATE_PROTO) {
2356 process_proto($file, $_); !! 2192 process_proto($file, $_);
2357 } elsif ($state == STATE_DOCBLOCK) { !! 2193 } elsif ($state == STATE_DOCBLOCK) {
2358 process_docblock($file, $_); !! 2194 process_docblock($file, $_);
2359 } !! 2195 }
2360 } 2196 }
2361 2197
2362 # Make sure we got something interesting. 2198 # Make sure we got something interesting.
2363 if ($initial_section_counter == $section_ 2199 if ($initial_section_counter == $section_counter && $
2364 output_mode ne "none") { !! 2200 output_mode ne "none") {
2365 if ($output_selection == OUTPUT_INCLU !! 2201 if ($output_selection == OUTPUT_INCLUDE) {
2366 emit_warning("${file}:1", "'$_' n !! 2202 print STDERR "${file}:1: warning: '$_' not found\n"
2367 for keys %function_table; !! 2203 for keys %function_table;
2368 } else { !! 2204 }
2369 emit_warning("${file}:1", "no str !! 2205 else {
2370 } !! 2206 print STDERR "${file}:1: warning: no structured comments found\n";
>> 2207 }
2371 } 2208 }
2372 close IN_FILE; <<
2373 } 2209 }
2374 2210
2375 2211
2376 if ($output_mode eq "rst") { <<
2377 get_sphinx_version() if (!$sphinx_major); <<
2378 } <<
2379 <<
2380 $kernelversion = get_kernel_version(); 2212 $kernelversion = get_kernel_version();
2381 2213
2382 # generate a sequence of code that will splic 2214 # generate a sequence of code that will splice in highlighting information
2383 # using the s// operator. 2215 # using the s// operator.
2384 for (my $k = 0; $k < @highlights; $k++) { 2216 for (my $k = 0; $k < @highlights; $k++) {
2385 my $pattern = $highlights[$k][0]; 2217 my $pattern = $highlights[$k][0];
2386 my $result = $highlights[$k][1]; 2218 my $result = $highlights[$k][1];
2387 # print STDERR "scanning pattern:$pattern, 2219 # print STDERR "scanning pattern:$pattern, highlight:($result)\n";
2388 $dohighlight .= "\$contents =~ s:$patter 2220 $dohighlight .= "\$contents =~ s:$pattern:$result:gs;\n";
2389 } 2221 }
2390 2222
2391 # Read the file that maps relative names to a 2223 # Read the file that maps relative names to absolute names for
2392 # separate source and object directories and 2224 # separate source and object directories and for shadow trees.
2393 if (open(SOURCE_MAP, "<.tmp_filelist.txt")) { 2225 if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
2394 my ($relname, $absname); !! 2226 my ($relname, $absname);
2395 while(<SOURCE_MAP>) { !! 2227 while(<SOURCE_MAP>) {
2396 chop(); !! 2228 chop();
2397 ($relname, $absname) = (split())[0..1 !! 2229 ($relname, $absname) = (split())[0..1];
2398 $relname =~ s:^/+::; !! 2230 $relname =~ s:^/+::;
2399 $source_map{$relname} = $absname; !! 2231 $source_map{$relname} = $absname;
2400 } !! 2232 }
2401 close(SOURCE_MAP); !! 2233 close(SOURCE_MAP);
2402 } 2234 }
2403 2235
2404 if ($output_selection == OUTPUT_EXPORTED || 2236 if ($output_selection == OUTPUT_EXPORTED ||
2405 $output_selection == OUTPUT_INTERNAL) { 2237 $output_selection == OUTPUT_INTERNAL) {
2406 2238
2407 push(@export_file_list, @ARGV); 2239 push(@export_file_list, @ARGV);
2408 2240
2409 foreach (@export_file_list) { 2241 foreach (@export_file_list) {
2410 chomp; !! 2242 chomp;
2411 process_export_file($_); !! 2243 process_export_file($_);
2412 } 2244 }
2413 } 2245 }
2414 2246
2415 foreach (@ARGV) { 2247 foreach (@ARGV) {
2416 chomp; 2248 chomp;
2417 process_file($_); 2249 process_file($_);
2418 } 2250 }
2419 if ($verbose && $errors) { 2251 if ($verbose && $errors) {
2420 print STDERR "$errors errors\n"; !! 2252 print STDERR "$errors errors\n";
2421 } 2253 }
2422 if ($verbose && $warnings) { 2254 if ($verbose && $warnings) {
2423 print STDERR "$warnings warnings\n"; !! 2255 print STDERR "$warnings warnings\n";
2424 } <<
2425 <<
2426 if ($Werror && $warnings) { <<
2427 print STDERR "$warnings warnings as Error <<
2428 exit($warnings); <<
2429 } else { <<
2430 exit($output_mode eq "none" ? 0 : $errors <<
2431 } 2256 }
2432 2257
2433 __END__ !! 2258 exit($output_mode eq "none" ? 0 : $errors);
2434 <<
2435 =head1 OPTIONS <<
2436 <<
2437 =head2 Output format selection (mutually excl <<
2438 <<
2439 =over 8 <<
2440 <<
2441 =item -man <<
2442 <<
2443 Output troff manual page format. <<
2444 <<
2445 =item -rst <<
2446 <<
2447 Output reStructuredText format. This is the d <<
2448 <<
2449 =item -none <<
2450 <<
2451 Do not output documentation, only warnings. <<
2452 <<
2453 =back <<
2454 <<
2455 =head2 Output format modifiers <<
2456 <<
2457 =head3 reStructuredText only <<
2458 <<
2459 =over 8 <<
2460 <<
2461 =item -sphinx-version VERSION <<
2462 <<
2463 Use the ReST C domain dialect compatible with <<
2464 <<
2465 If not specified, kernel-doc will auto-detect <<
2466 found on PATH. <<
2467 <<
2468 =back <<
2469 <<
2470 =head2 Output selection (mutually exclusive): <<
2471 <<
2472 =over 8 <<
2473 <<
2474 =item -export <<
2475 <<
2476 Only output documentation for the symbols tha <<
2477 EXPORT_SYMBOL() and related macros in any inp <<
2478 <<
2479 =item -internal <<
2480 <<
2481 Only output documentation for the symbols tha <<
2482 EXPORT_SYMBOL() and related macros in any inp <<
2483 <<
2484 =item -function NAME <<
2485 <<
2486 Only output documentation for the given funct <<
2487 All other functions and DOC: sections are ign <<
2488 <<
2489 May be specified multiple times. <<
2490 <<
2491 =item -nosymbol NAME <<
2492 <<
2493 Exclude the specified symbol from the output <<
2494 <<
2495 May be specified multiple times. <<
2496 <<
2497 =back <<
2498 <<
2499 =head2 Output selection modifiers: <<
2500 <<
2501 =over 8 <<
2502 <<
2503 =item -no-doc-sections <<
2504 <<
2505 Do not output DOC: sections. <<
2506 <<
2507 =item -export-file FILE <<
2508 <<
2509 Specify an additional FILE in which to look f <<
2510 <<
2511 To be used with -export or -internal. <<
2512 <<
2513 May be specified multiple times. <<
2514 <<
2515 =back <<
2516 <<
2517 =head3 reStructuredText only <<
2518 <<
2519 =over 8 <<
2520 <<
2521 =item -enable-lineno <<
2522 <<
2523 Enable output of .. LINENO lines. <<
2524 <<
2525 =back <<
2526 <<
2527 =head2 Other parameters: <<
2528 <<
2529 =over 8 <<
2530 <<
2531 =item -h, -help <<
2532 <<
2533 Print this help. <<
2534 <<
2535 =item -v <<
2536 <<
2537 Verbose output, more warnings and other infor <<
2538 <<
2539 =item -Werror <<
2540 <<
2541 Treat warnings as errors. <<
2542 <<
2543 =back <<
2544 <<
2545 =cut <<
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.