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