Merge branch 'x86-urgent-for-linus' of git://git.kernel.org/pub/scm/linux/kernel...
[linux/fpc-iii.git] / scripts / kernel-doc
blob2fc8fad5195e8994a320013cd8c731a0d9469f63
1 #!/usr/bin/perl -w
3 use strict;
5 ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
6 ## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
7 ## Copyright (C) 2001 Simon Huggins ##
8 ## Copyright (C) 2005-2012 Randy Dunlap ##
9 ## Copyright (C) 2012 Dan Luedtke ##
10 ## ##
11 ## #define enhancements by Armin Kuster <akuster@mvista.com> ##
12 ## Copyright (c) 2000 MontaVista Software, Inc. ##
13 ## ##
14 ## This software falls under the GNU General Public License. ##
15 ## Please read the COPYING file for more information ##
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
22 # 27/06/2001 - Allowed whitespace after initial "/**" and
23 # allowed comments before function declarations.
24 # -- Christian Kreibich <ck@whoop.org>
26 # Still to do:
27 # - add perldoc documentation
28 # - Look more closely at some of the scarier bits :)
30 # 26/05/2001 - Support for separate source and object trees.
31 # Return error code.
32 # Keith Owens <kaos@ocs.com.au>
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>
39 # 25/07/2012 - Added support for HTML5
40 # -- Dan Luedtke <mail@danrl.de>
42 sub usage {
43 my $message = <<"EOF";
44 Usage: $0 [OPTION ...] FILE ...
46 Read C language source or header FILEs, extract embedded documentation comments,
47 and print formatted documentation to standard output.
49 The documentation comments are identified by "/**" opening comment mark. See
50 Documentation/kernel-doc-nano-HOWTO.txt for the documentation comment syntax.
52 Output format selection (mutually exclusive):
53 -docbook Output DocBook format.
54 -html Output HTML format.
55 -html5 Output HTML5 format.
56 -list Output symbol list format. This is for use by docproc.
57 -man Output troff manual page format. This is the default.
58 -rst Output reStructuredText format.
59 -text Output plain text format.
61 Output selection (mutually exclusive):
62 -function NAME Only output documentation for the given function(s)
63 or DOC: section title(s). All other functions and DOC:
64 sections are ignored. May be specified multiple times.
65 -nofunction NAME Do NOT output documentation for the given function(s);
66 only output documentation for the other functions and
67 DOC: sections. May be specified multiple times.
69 Output selection modifiers:
70 -no-doc-sections Do not output DOC: sections.
72 Other parameters:
73 -v Verbose output, more warnings and other information.
74 -h Print this help.
76 EOF
77 print $message;
78 exit 1;
82 # format of comments.
83 # In the following table, (...)? signifies optional structure.
84 # (...)* signifies 0 or more structure elements
85 # /**
86 # * function_name(:)? (- short description)?
87 # (* @parameterx: (description of parameter x)?)*
88 # (* a blank line)?
89 # * (Description:)? (Description of function)?
90 # * (section header: (section description)? )*
91 # (*)?*/
93 # So .. the trivial example would be:
95 # /**
96 # * my_function
97 # */
99 # If the Description: header tag is omitted, then there must be a blank line
100 # after the last parameter specification.
101 # e.g.
102 # /**
103 # * my_function - does my stuff
104 # * @my_arg: its mine damnit
106 # * Does my stuff explained.
107 # */
109 # or, could also use:
110 # /**
111 # * my_function - does my stuff
112 # * @my_arg: its mine damnit
113 # * Description: Does my stuff explained.
114 # */
115 # etc.
117 # Besides functions you can also write documentation for structs, unions,
118 # enums and typedefs. Instead of the function name you must write the name
119 # of the declaration; the struct/union/enum/typedef must always precede
120 # the name. Nesting of declarations is not supported.
121 # Use the argument mechanism to document members or constants.
122 # e.g.
123 # /**
124 # * struct my_struct - short description
125 # * @a: first member
126 # * @b: second member
128 # * Longer description
129 # */
130 # struct my_struct {
131 # int a;
132 # int b;
133 # /* private: */
134 # int c;
135 # };
137 # All descriptions can be multiline, except the short function description.
139 # For really longs structs, you can also describe arguments inside the
140 # body of the struct.
141 # eg.
142 # /**
143 # * struct my_struct - short description
144 # * @a: first member
145 # * @b: second member
147 # * Longer description
148 # */
149 # struct my_struct {
150 # int a;
151 # int b;
152 # /**
153 # * @c: This is longer description of C
155 # * You can use paragraphs to describe arguments
156 # * using this method.
157 # */
158 # int c;
159 # };
161 # This should be use only for struct/enum members.
163 # You can also add additional sections. When documenting kernel functions you
164 # should document the "Context:" of the function, e.g. whether the functions
165 # can be called form interrupts. Unlike other sections you can end it with an
166 # empty line.
167 # A non-void function should have a "Return:" section describing the return
168 # value(s).
169 # Example-sections should contain the string EXAMPLE so that they are marked
170 # appropriately in DocBook.
172 # Example:
173 # /**
174 # * user_function - function that can only be called in user context
175 # * @a: some argument
176 # * Context: !in_interrupt()
178 # * Some description
179 # * Example:
180 # * user_function(22);
181 # */
182 # ...
185 # All descriptive text is further processed, scanning for the following special
186 # patterns, which are highlighted appropriately.
188 # 'funcname()' - function
189 # '$ENVVAR' - environmental variable
190 # '&struct_name' - name of a structure (up to two words including 'struct')
191 # '@parameter' - name of a parameter
192 # '%CONST' - name of a constant.
194 ## init lots of data
196 my $errors = 0;
197 my $warnings = 0;
198 my $anon_struct_union = 0;
200 # match expressions used to find embedded type information
201 my $type_constant = '\%([-_\w]+)';
202 my $type_func = '(\w+)\(\)';
203 my $type_param = '\@(\w+)';
204 my $type_struct = '\&((struct\s*)*[_\w]+)';
205 my $type_struct_xml = '\\&amp;((struct\s*)*[_\w]+)';
206 my $type_env = '(\$\w+)';
207 my $type_enum_full = '\&(enum)\s*([_\w]+)';
208 my $type_struct_full = '\&(struct)\s*([_\w]+)';
210 # Output conversion substitutions.
211 # One for each output format
213 # these work fairly well
214 my @highlights_html = (
215 [$type_constant, "<i>\$1</i>"],
216 [$type_func, "<b>\$1</b>"],
217 [$type_struct_xml, "<i>\$1</i>"],
218 [$type_env, "<b><i>\$1</i></b>"],
219 [$type_param, "<tt><b>\$1</b></tt>"]
221 my $local_lt = "\\\\\\\\lt:";
222 my $local_gt = "\\\\\\\\gt:";
223 my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>"
225 # html version 5
226 my @highlights_html5 = (
227 [$type_constant, "<span class=\"const\">\$1</span>"],
228 [$type_func, "<span class=\"func\">\$1</span>"],
229 [$type_struct_xml, "<span class=\"struct\">\$1</span>"],
230 [$type_env, "<span class=\"env\">\$1</span>"],
231 [$type_param, "<span class=\"param\">\$1</span>]"]
233 my $blankline_html5 = $local_lt . "br /" . $local_gt;
235 # XML, docbook format
236 my @highlights_xml = (
237 ["([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>"],
238 [$type_constant, "<constant>\$1</constant>"],
239 [$type_struct_xml, "<structname>\$1</structname>"],
240 [$type_param, "<parameter>\$1</parameter>"],
241 [$type_func, "<function>\$1</function>"],
242 [$type_env, "<envar>\$1</envar>"]
244 my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
246 # gnome, docbook format
247 my @highlights_gnome = (
248 [$type_constant, "<replaceable class=\"option\">\$1</replaceable>"],
249 [$type_func, "<function>\$1</function>"],
250 [$type_struct, "<structname>\$1</structname>"],
251 [$type_env, "<envar>\$1</envar>"],
252 [$type_param, "<parameter>\$1</parameter>" ]
254 my $blankline_gnome = "</para><para>\n";
256 # these are pretty rough
257 my @highlights_man = (
258 [$type_constant, "\$1"],
259 [$type_func, "\\\\fB\$1\\\\fP"],
260 [$type_struct, "\\\\fI\$1\\\\fP"],
261 [$type_param, "\\\\fI\$1\\\\fP"]
263 my $blankline_man = "";
265 # text-mode
266 my @highlights_text = (
267 [$type_constant, "\$1"],
268 [$type_func, "\$1"],
269 [$type_struct, "\$1"],
270 [$type_param, "\$1"]
272 my $blankline_text = "";
274 # rst-mode
275 my @highlights_rst = (
276 [$type_constant, "``\$1``"],
277 [$type_func, "\\:c\\:func\\:`\$1`"],
278 [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
279 [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
280 [$type_struct, "\\:c\\:type\\:`struct \$1 <\$1>`"],
281 [$type_param, "**\$1**"]
283 my $blankline_rst = "\n";
285 # list mode
286 my @highlights_list = (
287 [$type_constant, "\$1"],
288 [$type_func, "\$1"],
289 [$type_struct, "\$1"],
290 [$type_param, "\$1"]
292 my $blankline_list = "";
294 # read arguments
295 if ($#ARGV == -1) {
296 usage();
299 my $kernelversion;
300 my $dohighlight = "";
302 my $verbose = 0;
303 my $output_mode = "man";
304 my $output_preformatted = 0;
305 my $no_doc_sections = 0;
306 my @highlights = @highlights_man;
307 my $blankline = $blankline_man;
308 my $modulename = "Kernel API";
309 my $function_only = 0;
310 my $show_not_found = 0;
312 my @build_time;
313 if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
314 (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
315 @build_time = gmtime($seconds);
316 } else {
317 @build_time = localtime;
320 my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
321 'July', 'August', 'September', 'October',
322 'November', 'December')[$build_time[4]] .
323 " " . ($build_time[5]+1900);
325 # Essentially these are globals.
326 # They probably want to be tidied up, made more localised or something.
327 # CAVEAT EMPTOR! Some of the others I localised may not want to be, which
328 # could cause "use of undefined value" or other bugs.
329 my ($function, %function_table, %parametertypes, $declaration_purpose);
330 my ($type, $declaration_name, $return_type);
331 my ($newsection, $newcontents, $prototype, $brcount, %source_map);
333 if (defined($ENV{'KBUILD_VERBOSE'})) {
334 $verbose = "$ENV{'KBUILD_VERBOSE'}";
337 # Generated docbook code is inserted in a template at a point where
338 # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
339 # http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
340 # We keep track of number of generated entries and generate a dummy
341 # if needs be to ensure the expanded template can be postprocessed
342 # into html.
343 my $section_counter = 0;
345 my $lineprefix="";
347 # states
348 # 0 - normal code
349 # 1 - looking for function name
350 # 2 - scanning field start.
351 # 3 - scanning prototype.
352 # 4 - documentation block
353 # 5 - gathering documentation outside main block
354 my $state;
355 my $in_doc_sect;
357 # Split Doc State
358 # 0 - Invalid (Before start or after finish)
359 # 1 - Is started (the /** was found inside a struct)
360 # 2 - The @parameter header was found, start accepting multi paragraph text.
361 # 3 - Finished (the */ was found)
362 # 4 - Error - Comment without header was found. Spit a warning as it's not
363 # proper kernel-doc and ignore the rest.
364 my $split_doc_state;
366 #declaration types: can be
367 # 'function', 'struct', 'union', 'enum', 'typedef'
368 my $decl_type;
370 my $doc_special = "\@\%\$\&";
372 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
373 my $doc_end = '\*/';
374 my $doc_com = '\s*\*\s*';
375 my $doc_com_body = '\s*\* ?';
376 my $doc_decl = $doc_com . '(\w+)';
377 my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
378 my $doc_content = $doc_com_body . '(.*)';
379 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
380 my $doc_split_start = '^\s*/\*\*\s*$';
381 my $doc_split_sect = '\s*\*\s*(@[\w\s]+):(.*)';
382 my $doc_split_end = '^\s*\*/\s*$';
384 my %constants;
385 my %parameterdescs;
386 my @parameterlist;
387 my %sections;
388 my @sectionlist;
389 my $sectcheck;
390 my $struct_actual;
392 my $contents = "";
393 my $section_default = "Description"; # default section
394 my $section_intro = "Introduction";
395 my $section = $section_default;
396 my $section_context = "Context";
397 my $section_return = "Return";
399 my $undescribed = "-- undescribed --";
401 reset_state();
403 while ($ARGV[0] =~ m/^-(.*)/) {
404 my $cmd = shift @ARGV;
405 if ($cmd eq "-html") {
406 $output_mode = "html";
407 @highlights = @highlights_html;
408 $blankline = $blankline_html;
409 } elsif ($cmd eq "-html5") {
410 $output_mode = "html5";
411 @highlights = @highlights_html5;
412 $blankline = $blankline_html5;
413 } elsif ($cmd eq "-man") {
414 $output_mode = "man";
415 @highlights = @highlights_man;
416 $blankline = $blankline_man;
417 } elsif ($cmd eq "-text") {
418 $output_mode = "text";
419 @highlights = @highlights_text;
420 $blankline = $blankline_text;
421 } elsif ($cmd eq "-rst") {
422 $output_mode = "rst";
423 @highlights = @highlights_rst;
424 $blankline = $blankline_rst;
425 } elsif ($cmd eq "-docbook") {
426 $output_mode = "xml";
427 @highlights = @highlights_xml;
428 $blankline = $blankline_xml;
429 } elsif ($cmd eq "-list") {
430 $output_mode = "list";
431 @highlights = @highlights_list;
432 $blankline = $blankline_list;
433 } elsif ($cmd eq "-gnome") {
434 $output_mode = "gnome";
435 @highlights = @highlights_gnome;
436 $blankline = $blankline_gnome;
437 } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
438 $modulename = shift @ARGV;
439 } elsif ($cmd eq "-function") { # to only output specific functions
440 $function_only = 1;
441 $function = shift @ARGV;
442 $function_table{$function} = 1;
443 } elsif ($cmd eq "-nofunction") { # to only output specific functions
444 $function_only = 2;
445 $function = shift @ARGV;
446 $function_table{$function} = 1;
447 } elsif ($cmd eq "-v") {
448 $verbose = 1;
449 } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
450 usage();
451 } elsif ($cmd eq '-no-doc-sections') {
452 $no_doc_sections = 1;
453 } elsif ($cmd eq '-show-not-found') {
454 $show_not_found = 1;
458 # continue execution near EOF;
460 # get kernel version from env
461 sub get_kernel_version() {
462 my $version = 'unknown kernel version';
464 if (defined($ENV{'KERNELVERSION'})) {
465 $version = $ENV{'KERNELVERSION'};
467 return $version;
471 # dumps section contents to arrays/hashes intended for that purpose.
473 sub dump_section {
474 my $file = shift;
475 my $name = shift;
476 my $contents = join "\n", @_;
478 if ($name =~ m/$type_constant/) {
479 $name = $1;
480 # print STDERR "constant section '$1' = '$contents'\n";
481 $constants{$name} = $contents;
482 } elsif ($name =~ m/$type_param/) {
483 # print STDERR "parameter def '$1' = '$contents'\n";
484 $name = $1;
485 $parameterdescs{$name} = $contents;
486 $sectcheck = $sectcheck . $name . " ";
487 } elsif ($name eq "@\.\.\.") {
488 # print STDERR "parameter def '...' = '$contents'\n";
489 $name = "...";
490 $parameterdescs{$name} = $contents;
491 $sectcheck = $sectcheck . $name . " ";
492 } else {
493 # print STDERR "other section '$name' = '$contents'\n";
494 if (defined($sections{$name}) && ($sections{$name} ne "")) {
495 print STDERR "${file}:$.: error: duplicate section name '$name'\n";
496 ++$errors;
498 $sections{$name} = $contents;
499 push @sectionlist, $name;
504 # dump DOC: section after checking that it should go out
506 sub dump_doc_section {
507 my $file = shift;
508 my $name = shift;
509 my $contents = join "\n", @_;
511 if ($no_doc_sections) {
512 return;
515 if (($function_only == 0) ||
516 ( $function_only == 1 && defined($function_table{$name})) ||
517 ( $function_only == 2 && !defined($function_table{$name})))
519 dump_section($file, $name, $contents);
520 output_blockhead({'sectionlist' => \@sectionlist,
521 'sections' => \%sections,
522 'module' => $modulename,
523 'content-only' => ($function_only != 0), });
528 # output function
530 # parameterdescs, a hash.
531 # function => "function name"
532 # parameterlist => @list of parameters
533 # parameterdescs => %parameter descriptions
534 # sectionlist => @list of sections
535 # sections => %section descriptions
538 sub output_highlight {
539 my $contents = join "\n",@_;
540 my $line;
542 # DEBUG
543 # if (!defined $contents) {
544 # use Carp;
545 # confess "output_highlight got called with no args?\n";
548 if ($output_mode eq "html" || $output_mode eq "html5" ||
549 $output_mode eq "xml") {
550 $contents = local_unescape($contents);
551 # convert data read & converted thru xml_escape() into &xyz; format:
552 $contents =~ s/\\\\\\/\&/g;
554 # print STDERR "contents b4:$contents\n";
555 eval $dohighlight;
556 die $@ if $@;
557 # print STDERR "contents af:$contents\n";
559 # strip whitespaces when generating html5
560 if ($output_mode eq "html5") {
561 $contents =~ s/^\s+//;
562 $contents =~ s/\s+$//;
564 foreach $line (split "\n", $contents) {
565 if (! $output_preformatted) {
566 $line =~ s/^\s*//;
568 if ($line eq ""){
569 if (! $output_preformatted) {
570 print $lineprefix, local_unescape($blankline);
572 } else {
573 $line =~ s/\\\\\\/\&/g;
574 if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
575 print "\\&$line";
576 } else {
577 print $lineprefix, $line;
580 print "\n";
584 # output sections in html
585 sub output_section_html(%) {
586 my %args = %{$_[0]};
587 my $section;
589 foreach $section (@{$args{'sectionlist'}}) {
590 print "<h3>$section</h3>\n";
591 print "<blockquote>\n";
592 output_highlight($args{'sections'}{$section});
593 print "</blockquote>\n";
597 # output enum in html
598 sub output_enum_html(%) {
599 my %args = %{$_[0]};
600 my ($parameter);
601 my $count;
602 print "<h2>enum " . $args{'enum'} . "</h2>\n";
604 print "<b>enum " . $args{'enum'} . "</b> {<br>\n";
605 $count = 0;
606 foreach $parameter (@{$args{'parameterlist'}}) {
607 print " <b>" . $parameter . "</b>";
608 if ($count != $#{$args{'parameterlist'}}) {
609 $count++;
610 print ",\n";
612 print "<br>";
614 print "};<br>\n";
616 print "<h3>Constants</h3>\n";
617 print "<dl>\n";
618 foreach $parameter (@{$args{'parameterlist'}}) {
619 print "<dt><b>" . $parameter . "</b>\n";
620 print "<dd>";
621 output_highlight($args{'parameterdescs'}{$parameter});
623 print "</dl>\n";
624 output_section_html(@_);
625 print "<hr>\n";
628 # output typedef in html
629 sub output_typedef_html(%) {
630 my %args = %{$_[0]};
631 my ($parameter);
632 my $count;
633 print "<h2>typedef " . $args{'typedef'} . "</h2>\n";
635 print "<b>typedef " . $args{'typedef'} . "</b>\n";
636 output_section_html(@_);
637 print "<hr>\n";
640 # output struct in html
641 sub output_struct_html(%) {
642 my %args = %{$_[0]};
643 my ($parameter);
645 print "<h2>" . $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "</h2>\n";
646 print "<b>" . $args{'type'} . " " . $args{'struct'} . "</b> {<br>\n";
647 foreach $parameter (@{$args{'parameterlist'}}) {
648 if ($parameter =~ /^#/) {
649 print "$parameter<br>\n";
650 next;
652 my $parameter_name = $parameter;
653 $parameter_name =~ s/\[.*//;
655 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
656 $type = $args{'parametertypes'}{$parameter};
657 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
658 # pointer-to-function
659 print "&nbsp; &nbsp; <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
660 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
661 # bitfield
662 print "&nbsp; &nbsp; <i>$1</i> <b>$parameter</b>$2;<br>\n";
663 } else {
664 print "&nbsp; &nbsp; <i>$type</i> <b>$parameter</b>;<br>\n";
667 print "};<br>\n";
669 print "<h3>Members</h3>\n";
670 print "<dl>\n";
671 foreach $parameter (@{$args{'parameterlist'}}) {
672 ($parameter =~ /^#/) && next;
674 my $parameter_name = $parameter;
675 $parameter_name =~ s/\[.*//;
677 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
678 print "<dt><b>" . $parameter . "</b>\n";
679 print "<dd>";
680 output_highlight($args{'parameterdescs'}{$parameter_name});
682 print "</dl>\n";
683 output_section_html(@_);
684 print "<hr>\n";
687 # output function in html
688 sub output_function_html(%) {
689 my %args = %{$_[0]};
690 my ($parameter, $section);
691 my $count;
693 print "<h2>" . $args{'function'} . " - " . $args{'purpose'} . "</h2>\n";
694 print "<i>" . $args{'functiontype'} . "</i>\n";
695 print "<b>" . $args{'function'} . "</b>\n";
696 print "(";
697 $count = 0;
698 foreach $parameter (@{$args{'parameterlist'}}) {
699 $type = $args{'parametertypes'}{$parameter};
700 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
701 # pointer-to-function
702 print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
703 } else {
704 print "<i>" . $type . "</i> <b>" . $parameter . "</b>";
706 if ($count != $#{$args{'parameterlist'}}) {
707 $count++;
708 print ",\n";
711 print ")\n";
713 print "<h3>Arguments</h3>\n";
714 print "<dl>\n";
715 foreach $parameter (@{$args{'parameterlist'}}) {
716 my $parameter_name = $parameter;
717 $parameter_name =~ s/\[.*//;
719 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
720 print "<dt><b>" . $parameter . "</b>\n";
721 print "<dd>";
722 output_highlight($args{'parameterdescs'}{$parameter_name});
724 print "</dl>\n";
725 output_section_html(@_);
726 print "<hr>\n";
729 # output DOC: block header in html
730 sub output_blockhead_html(%) {
731 my %args = %{$_[0]};
732 my ($parameter, $section);
733 my $count;
735 foreach $section (@{$args{'sectionlist'}}) {
736 print "<h3>$section</h3>\n";
737 print "<ul>\n";
738 output_highlight($args{'sections'}{$section});
739 print "</ul>\n";
741 print "<hr>\n";
744 # output sections in html5
745 sub output_section_html5(%) {
746 my %args = %{$_[0]};
747 my $section;
749 foreach $section (@{$args{'sectionlist'}}) {
750 print "<section>\n";
751 print "<h1>$section</h1>\n";
752 print "<p>\n";
753 output_highlight($args{'sections'}{$section});
754 print "</p>\n";
755 print "</section>\n";
759 # output enum in html5
760 sub output_enum_html5(%) {
761 my %args = %{$_[0]};
762 my ($parameter);
763 my $count;
764 my $html5id;
766 $html5id = $args{'enum'};
767 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
768 print "<article class=\"enum\" id=\"enum:". $html5id . "\">";
769 print "<h1>enum " . $args{'enum'} . "</h1>\n";
770 print "<ol class=\"code\">\n";
771 print "<li>";
772 print "<span class=\"keyword\">enum</span> ";
773 print "<span class=\"identifier\">" . $args{'enum'} . "</span> {";
774 print "</li>\n";
775 $count = 0;
776 foreach $parameter (@{$args{'parameterlist'}}) {
777 print "<li class=\"indent\">";
778 print "<span class=\"param\">" . $parameter . "</span>";
779 if ($count != $#{$args{'parameterlist'}}) {
780 $count++;
781 print ",";
783 print "</li>\n";
785 print "<li>};</li>\n";
786 print "</ol>\n";
788 print "<section>\n";
789 print "<h1>Constants</h1>\n";
790 print "<dl>\n";
791 foreach $parameter (@{$args{'parameterlist'}}) {
792 print "<dt>" . $parameter . "</dt>\n";
793 print "<dd>";
794 output_highlight($args{'parameterdescs'}{$parameter});
795 print "</dd>\n";
797 print "</dl>\n";
798 print "</section>\n";
799 output_section_html5(@_);
800 print "</article>\n";
803 # output typedef in html5
804 sub output_typedef_html5(%) {
805 my %args = %{$_[0]};
806 my ($parameter);
807 my $count;
808 my $html5id;
810 $html5id = $args{'typedef'};
811 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
812 print "<article class=\"typedef\" id=\"typedef:" . $html5id . "\">\n";
813 print "<h1>typedef " . $args{'typedef'} . "</h1>\n";
815 print "<ol class=\"code\">\n";
816 print "<li>";
817 print "<span class=\"keyword\">typedef</span> ";
818 print "<span class=\"identifier\">" . $args{'typedef'} . "</span>";
819 print "</li>\n";
820 print "</ol>\n";
821 output_section_html5(@_);
822 print "</article>\n";
825 # output struct in html5
826 sub output_struct_html5(%) {
827 my %args = %{$_[0]};
828 my ($parameter);
829 my $html5id;
831 $html5id = $args{'struct'};
832 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
833 print "<article class=\"struct\" id=\"struct:" . $html5id . "\">\n";
834 print "<hgroup>\n";
835 print "<h1>" . $args{'type'} . " " . $args{'struct'} . "</h1>";
836 print "<h2>". $args{'purpose'} . "</h2>\n";
837 print "</hgroup>\n";
838 print "<ol class=\"code\">\n";
839 print "<li>";
840 print "<span class=\"type\">" . $args{'type'} . "</span> ";
841 print "<span class=\"identifier\">" . $args{'struct'} . "</span> {";
842 print "</li>\n";
843 foreach $parameter (@{$args{'parameterlist'}}) {
844 print "<li class=\"indent\">";
845 if ($parameter =~ /^#/) {
846 print "<span class=\"param\">" . $parameter ."</span>\n";
847 print "</li>\n";
848 next;
850 my $parameter_name = $parameter;
851 $parameter_name =~ s/\[.*//;
853 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
854 $type = $args{'parametertypes'}{$parameter};
855 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
856 # pointer-to-function
857 print "<span class=\"type\">$1</span> ";
858 print "<span class=\"param\">$parameter</span>";
859 print "<span class=\"type\">)</span> ";
860 print "(<span class=\"args\">$2</span>);";
861 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
862 # bitfield
863 print "<span class=\"type\">$1</span> ";
864 print "<span class=\"param\">$parameter</span>";
865 print "<span class=\"bits\">$2</span>;";
866 } else {
867 print "<span class=\"type\">$type</span> ";
868 print "<span class=\"param\">$parameter</span>;";
870 print "</li>\n";
872 print "<li>};</li>\n";
873 print "</ol>\n";
875 print "<section>\n";
876 print "<h1>Members</h1>\n";
877 print "<dl>\n";
878 foreach $parameter (@{$args{'parameterlist'}}) {
879 ($parameter =~ /^#/) && next;
881 my $parameter_name = $parameter;
882 $parameter_name =~ s/\[.*//;
884 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
885 print "<dt>" . $parameter . "</dt>\n";
886 print "<dd>";
887 output_highlight($args{'parameterdescs'}{$parameter_name});
888 print "</dd>\n";
890 print "</dl>\n";
891 print "</section>\n";
892 output_section_html5(@_);
893 print "</article>\n";
896 # output function in html5
897 sub output_function_html5(%) {
898 my %args = %{$_[0]};
899 my ($parameter, $section);
900 my $count;
901 my $html5id;
903 $html5id = $args{'function'};
904 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
905 print "<article class=\"function\" id=\"func:". $html5id . "\">\n";
906 print "<hgroup>\n";
907 print "<h1>" . $args{'function'} . "</h1>";
908 print "<h2>" . $args{'purpose'} . "</h2>\n";
909 print "</hgroup>\n";
910 print "<ol class=\"code\">\n";
911 print "<li>";
912 print "<span class=\"type\">" . $args{'functiontype'} . "</span> ";
913 print "<span class=\"identifier\">" . $args{'function'} . "</span> (";
914 print "</li>";
915 $count = 0;
916 foreach $parameter (@{$args{'parameterlist'}}) {
917 print "<li class=\"indent\">";
918 $type = $args{'parametertypes'}{$parameter};
919 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
920 # pointer-to-function
921 print "<span class=\"type\">$1</span> ";
922 print "<span class=\"param\">$parameter</span>";
923 print "<span class=\"type\">)</span> ";
924 print "(<span class=\"args\">$2</span>)";
925 } else {
926 print "<span class=\"type\">$type</span> ";
927 print "<span class=\"param\">$parameter</span>";
929 if ($count != $#{$args{'parameterlist'}}) {
930 $count++;
931 print ",";
933 print "</li>\n";
935 print "<li>)</li>\n";
936 print "</ol>\n";
938 print "<section>\n";
939 print "<h1>Arguments</h1>\n";
940 print "<p>\n";
941 print "<dl>\n";
942 foreach $parameter (@{$args{'parameterlist'}}) {
943 my $parameter_name = $parameter;
944 $parameter_name =~ s/\[.*//;
946 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
947 print "<dt>" . $parameter . "</dt>\n";
948 print "<dd>";
949 output_highlight($args{'parameterdescs'}{$parameter_name});
950 print "</dd>\n";
952 print "</dl>\n";
953 print "</section>\n";
954 output_section_html5(@_);
955 print "</article>\n";
958 # output DOC: block header in html5
959 sub output_blockhead_html5(%) {
960 my %args = %{$_[0]};
961 my ($parameter, $section);
962 my $count;
963 my $html5id;
965 foreach $section (@{$args{'sectionlist'}}) {
966 $html5id = $section;
967 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
968 print "<article class=\"doc\" id=\"doc:". $html5id . "\">\n";
969 print "<h1>$section</h1>\n";
970 print "<p>\n";
971 output_highlight($args{'sections'}{$section});
972 print "</p>\n";
974 print "</article>\n";
977 sub output_section_xml(%) {
978 my %args = %{$_[0]};
979 my $section;
980 # print out each section
981 $lineprefix=" ";
982 foreach $section (@{$args{'sectionlist'}}) {
983 print "<refsect1>\n";
984 print "<title>$section</title>\n";
985 if ($section =~ m/EXAMPLE/i) {
986 print "<informalexample><programlisting>\n";
987 $output_preformatted = 1;
988 } else {
989 print "<para>\n";
991 output_highlight($args{'sections'}{$section});
992 $output_preformatted = 0;
993 if ($section =~ m/EXAMPLE/i) {
994 print "</programlisting></informalexample>\n";
995 } else {
996 print "</para>\n";
998 print "</refsect1>\n";
1002 # output function in XML DocBook
1003 sub output_function_xml(%) {
1004 my %args = %{$_[0]};
1005 my ($parameter, $section);
1006 my $count;
1007 my $id;
1009 $id = "API-" . $args{'function'};
1010 $id =~ s/[^A-Za-z0-9]/-/g;
1012 print "<refentry id=\"$id\">\n";
1013 print "<refentryinfo>\n";
1014 print " <title>LINUX</title>\n";
1015 print " <productname>Kernel Hackers Manual</productname>\n";
1016 print " <date>$man_date</date>\n";
1017 print "</refentryinfo>\n";
1018 print "<refmeta>\n";
1019 print " <refentrytitle><phrase>" . $args{'function'} . "</phrase></refentrytitle>\n";
1020 print " <manvolnum>9</manvolnum>\n";
1021 print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
1022 print "</refmeta>\n";
1023 print "<refnamediv>\n";
1024 print " <refname>" . $args{'function'} . "</refname>\n";
1025 print " <refpurpose>\n";
1026 print " ";
1027 output_highlight ($args{'purpose'});
1028 print " </refpurpose>\n";
1029 print "</refnamediv>\n";
1031 print "<refsynopsisdiv>\n";
1032 print " <title>Synopsis</title>\n";
1033 print " <funcsynopsis><funcprototype>\n";
1034 print " <funcdef>" . $args{'functiontype'} . " ";
1035 print "<function>" . $args{'function'} . " </function></funcdef>\n";
1037 $count = 0;
1038 if ($#{$args{'parameterlist'}} >= 0) {
1039 foreach $parameter (@{$args{'parameterlist'}}) {
1040 $type = $args{'parametertypes'}{$parameter};
1041 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1042 # pointer-to-function
1043 print " <paramdef>$1<parameter>$parameter</parameter>)\n";
1044 print " <funcparams>$2</funcparams></paramdef>\n";
1045 } else {
1046 print " <paramdef>" . $type;
1047 print " <parameter>$parameter</parameter></paramdef>\n";
1050 } else {
1051 print " <void/>\n";
1053 print " </funcprototype></funcsynopsis>\n";
1054 print "</refsynopsisdiv>\n";
1056 # print parameters
1057 print "<refsect1>\n <title>Arguments</title>\n";
1058 if ($#{$args{'parameterlist'}} >= 0) {
1059 print " <variablelist>\n";
1060 foreach $parameter (@{$args{'parameterlist'}}) {
1061 my $parameter_name = $parameter;
1062 $parameter_name =~ s/\[.*//;
1064 print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n";
1065 print " <listitem>\n <para>\n";
1066 $lineprefix=" ";
1067 output_highlight($args{'parameterdescs'}{$parameter_name});
1068 print " </para>\n </listitem>\n </varlistentry>\n";
1070 print " </variablelist>\n";
1071 } else {
1072 print " <para>\n None\n </para>\n";
1074 print "</refsect1>\n";
1076 output_section_xml(@_);
1077 print "</refentry>\n\n";
1080 # output struct in XML DocBook
1081 sub output_struct_xml(%) {
1082 my %args = %{$_[0]};
1083 my ($parameter, $section);
1084 my $id;
1086 $id = "API-struct-" . $args{'struct'};
1087 $id =~ s/[^A-Za-z0-9]/-/g;
1089 print "<refentry id=\"$id\">\n";
1090 print "<refentryinfo>\n";
1091 print " <title>LINUX</title>\n";
1092 print " <productname>Kernel Hackers Manual</productname>\n";
1093 print " <date>$man_date</date>\n";
1094 print "</refentryinfo>\n";
1095 print "<refmeta>\n";
1096 print " <refentrytitle><phrase>" . $args{'type'} . " " . $args{'struct'} . "</phrase></refentrytitle>\n";
1097 print " <manvolnum>9</manvolnum>\n";
1098 print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
1099 print "</refmeta>\n";
1100 print "<refnamediv>\n";
1101 print " <refname>" . $args{'type'} . " " . $args{'struct'} . "</refname>\n";
1102 print " <refpurpose>\n";
1103 print " ";
1104 output_highlight ($args{'purpose'});
1105 print " </refpurpose>\n";
1106 print "</refnamediv>\n";
1108 print "<refsynopsisdiv>\n";
1109 print " <title>Synopsis</title>\n";
1110 print " <programlisting>\n";
1111 print $args{'type'} . " " . $args{'struct'} . " {\n";
1112 foreach $parameter (@{$args{'parameterlist'}}) {
1113 if ($parameter =~ /^#/) {
1114 my $prm = $parameter;
1115 # convert data read & converted thru xml_escape() into &xyz; format:
1116 # This allows us to have #define macros interspersed in a struct.
1117 $prm =~ s/\\\\\\/\&/g;
1118 print "$prm\n";
1119 next;
1122 my $parameter_name = $parameter;
1123 $parameter_name =~ s/\[.*//;
1125 defined($args{'parameterdescs'}{$parameter_name}) || next;
1126 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1127 $type = $args{'parametertypes'}{$parameter};
1128 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1129 # pointer-to-function
1130 print " $1 $parameter) ($2);\n";
1131 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1132 # bitfield
1133 print " $1 $parameter$2;\n";
1134 } else {
1135 print " " . $type . " " . $parameter . ";\n";
1138 print "};";
1139 print " </programlisting>\n";
1140 print "</refsynopsisdiv>\n";
1142 print " <refsect1>\n";
1143 print " <title>Members</title>\n";
1145 if ($#{$args{'parameterlist'}} >= 0) {
1146 print " <variablelist>\n";
1147 foreach $parameter (@{$args{'parameterlist'}}) {
1148 ($parameter =~ /^#/) && next;
1150 my $parameter_name = $parameter;
1151 $parameter_name =~ s/\[.*//;
1153 defined($args{'parameterdescs'}{$parameter_name}) || next;
1154 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1155 print " <varlistentry>";
1156 print " <term>$parameter</term>\n";
1157 print " <listitem><para>\n";
1158 output_highlight($args{'parameterdescs'}{$parameter_name});
1159 print " </para></listitem>\n";
1160 print " </varlistentry>\n";
1162 print " </variablelist>\n";
1163 } else {
1164 print " <para>\n None\n </para>\n";
1166 print " </refsect1>\n";
1168 output_section_xml(@_);
1170 print "</refentry>\n\n";
1173 # output enum in XML DocBook
1174 sub output_enum_xml(%) {
1175 my %args = %{$_[0]};
1176 my ($parameter, $section);
1177 my $count;
1178 my $id;
1180 $id = "API-enum-" . $args{'enum'};
1181 $id =~ s/[^A-Za-z0-9]/-/g;
1183 print "<refentry id=\"$id\">\n";
1184 print "<refentryinfo>\n";
1185 print " <title>LINUX</title>\n";
1186 print " <productname>Kernel Hackers Manual</productname>\n";
1187 print " <date>$man_date</date>\n";
1188 print "</refentryinfo>\n";
1189 print "<refmeta>\n";
1190 print " <refentrytitle><phrase>enum " . $args{'enum'} . "</phrase></refentrytitle>\n";
1191 print " <manvolnum>9</manvolnum>\n";
1192 print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
1193 print "</refmeta>\n";
1194 print "<refnamediv>\n";
1195 print " <refname>enum " . $args{'enum'} . "</refname>\n";
1196 print " <refpurpose>\n";
1197 print " ";
1198 output_highlight ($args{'purpose'});
1199 print " </refpurpose>\n";
1200 print "</refnamediv>\n";
1202 print "<refsynopsisdiv>\n";
1203 print " <title>Synopsis</title>\n";
1204 print " <programlisting>\n";
1205 print "enum " . $args{'enum'} . " {\n";
1206 $count = 0;
1207 foreach $parameter (@{$args{'parameterlist'}}) {
1208 print " $parameter";
1209 if ($count != $#{$args{'parameterlist'}}) {
1210 $count++;
1211 print ",";
1213 print "\n";
1215 print "};";
1216 print " </programlisting>\n";
1217 print "</refsynopsisdiv>\n";
1219 print "<refsect1>\n";
1220 print " <title>Constants</title>\n";
1221 print " <variablelist>\n";
1222 foreach $parameter (@{$args{'parameterlist'}}) {
1223 my $parameter_name = $parameter;
1224 $parameter_name =~ s/\[.*//;
1226 print " <varlistentry>";
1227 print " <term>$parameter</term>\n";
1228 print " <listitem><para>\n";
1229 output_highlight($args{'parameterdescs'}{$parameter_name});
1230 print " </para></listitem>\n";
1231 print " </varlistentry>\n";
1233 print " </variablelist>\n";
1234 print "</refsect1>\n";
1236 output_section_xml(@_);
1238 print "</refentry>\n\n";
1241 # output typedef in XML DocBook
1242 sub output_typedef_xml(%) {
1243 my %args = %{$_[0]};
1244 my ($parameter, $section);
1245 my $id;
1247 $id = "API-typedef-" . $args{'typedef'};
1248 $id =~ s/[^A-Za-z0-9]/-/g;
1250 print "<refentry id=\"$id\">\n";
1251 print "<refentryinfo>\n";
1252 print " <title>LINUX</title>\n";
1253 print " <productname>Kernel Hackers Manual</productname>\n";
1254 print " <date>$man_date</date>\n";
1255 print "</refentryinfo>\n";
1256 print "<refmeta>\n";
1257 print " <refentrytitle><phrase>typedef " . $args{'typedef'} . "</phrase></refentrytitle>\n";
1258 print " <manvolnum>9</manvolnum>\n";
1259 print "</refmeta>\n";
1260 print "<refnamediv>\n";
1261 print " <refname>typedef " . $args{'typedef'} . "</refname>\n";
1262 print " <refpurpose>\n";
1263 print " ";
1264 output_highlight ($args{'purpose'});
1265 print " </refpurpose>\n";
1266 print "</refnamediv>\n";
1268 print "<refsynopsisdiv>\n";
1269 print " <title>Synopsis</title>\n";
1270 print " <synopsis>typedef " . $args{'typedef'} . ";</synopsis>\n";
1271 print "</refsynopsisdiv>\n";
1273 output_section_xml(@_);
1275 print "</refentry>\n\n";
1278 # output in XML DocBook
1279 sub output_blockhead_xml(%) {
1280 my %args = %{$_[0]};
1281 my ($parameter, $section);
1282 my $count;
1284 my $id = $args{'module'};
1285 $id =~ s/[^A-Za-z0-9]/-/g;
1287 # print out each section
1288 $lineprefix=" ";
1289 foreach $section (@{$args{'sectionlist'}}) {
1290 if (!$args{'content-only'}) {
1291 print "<refsect1>\n <title>$section</title>\n";
1293 if ($section =~ m/EXAMPLE/i) {
1294 print "<example><para>\n";
1295 $output_preformatted = 1;
1296 } else {
1297 print "<para>\n";
1299 output_highlight($args{'sections'}{$section});
1300 $output_preformatted = 0;
1301 if ($section =~ m/EXAMPLE/i) {
1302 print "</para></example>\n";
1303 } else {
1304 print "</para>";
1306 if (!$args{'content-only'}) {
1307 print "\n</refsect1>\n";
1311 print "\n\n";
1314 # output in XML DocBook
1315 sub output_function_gnome {
1316 my %args = %{$_[0]};
1317 my ($parameter, $section);
1318 my $count;
1319 my $id;
1321 $id = $args{'module'} . "-" . $args{'function'};
1322 $id =~ s/[^A-Za-z0-9]/-/g;
1324 print "<sect2>\n";
1325 print " <title id=\"$id\">" . $args{'function'} . "</title>\n";
1327 print " <funcsynopsis>\n";
1328 print " <funcdef>" . $args{'functiontype'} . " ";
1329 print "<function>" . $args{'function'} . " ";
1330 print "</function></funcdef>\n";
1332 $count = 0;
1333 if ($#{$args{'parameterlist'}} >= 0) {
1334 foreach $parameter (@{$args{'parameterlist'}}) {
1335 $type = $args{'parametertypes'}{$parameter};
1336 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1337 # pointer-to-function
1338 print " <paramdef>$1 <parameter>$parameter</parameter>)\n";
1339 print " <funcparams>$2</funcparams></paramdef>\n";
1340 } else {
1341 print " <paramdef>" . $type;
1342 print " <parameter>$parameter</parameter></paramdef>\n";
1345 } else {
1346 print " <void>\n";
1348 print " </funcsynopsis>\n";
1349 if ($#{$args{'parameterlist'}} >= 0) {
1350 print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
1351 print "<tgroup cols=\"2\">\n";
1352 print "<colspec colwidth=\"2*\">\n";
1353 print "<colspec colwidth=\"8*\">\n";
1354 print "<tbody>\n";
1355 foreach $parameter (@{$args{'parameterlist'}}) {
1356 my $parameter_name = $parameter;
1357 $parameter_name =~ s/\[.*//;
1359 print " <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
1360 print " <entry>\n";
1361 $lineprefix=" ";
1362 output_highlight($args{'parameterdescs'}{$parameter_name});
1363 print " </entry></row>\n";
1365 print " </tbody></tgroup></informaltable>\n";
1366 } else {
1367 print " <para>\n None\n </para>\n";
1370 # print out each section
1371 $lineprefix=" ";
1372 foreach $section (@{$args{'sectionlist'}}) {
1373 print "<simplesect>\n <title>$section</title>\n";
1374 if ($section =~ m/EXAMPLE/i) {
1375 print "<example><programlisting>\n";
1376 $output_preformatted = 1;
1377 } else {
1379 print "<para>\n";
1380 output_highlight($args{'sections'}{$section});
1381 $output_preformatted = 0;
1382 print "</para>\n";
1383 if ($section =~ m/EXAMPLE/i) {
1384 print "</programlisting></example>\n";
1385 } else {
1387 print " </simplesect>\n";
1390 print "</sect2>\n\n";
1394 # output function in man
1395 sub output_function_man(%) {
1396 my %args = %{$_[0]};
1397 my ($parameter, $section);
1398 my $count;
1400 print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
1402 print ".SH NAME\n";
1403 print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
1405 print ".SH SYNOPSIS\n";
1406 if ($args{'functiontype'} ne "") {
1407 print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
1408 } else {
1409 print ".B \"" . $args{'function'} . "\n";
1411 $count = 0;
1412 my $parenth = "(";
1413 my $post = ",";
1414 foreach my $parameter (@{$args{'parameterlist'}}) {
1415 if ($count == $#{$args{'parameterlist'}}) {
1416 $post = ");";
1418 $type = $args{'parametertypes'}{$parameter};
1419 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1420 # pointer-to-function
1421 print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n";
1422 } else {
1423 $type =~ s/([^\*])$/$1 /;
1424 print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n";
1426 $count++;
1427 $parenth = "";
1430 print ".SH ARGUMENTS\n";
1431 foreach $parameter (@{$args{'parameterlist'}}) {
1432 my $parameter_name = $parameter;
1433 $parameter_name =~ s/\[.*//;
1435 print ".IP \"" . $parameter . "\" 12\n";
1436 output_highlight($args{'parameterdescs'}{$parameter_name});
1438 foreach $section (@{$args{'sectionlist'}}) {
1439 print ".SH \"", uc $section, "\"\n";
1440 output_highlight($args{'sections'}{$section});
1445 # output enum in man
1446 sub output_enum_man(%) {
1447 my %args = %{$_[0]};
1448 my ($parameter, $section);
1449 my $count;
1451 print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
1453 print ".SH NAME\n";
1454 print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
1456 print ".SH SYNOPSIS\n";
1457 print "enum " . $args{'enum'} . " {\n";
1458 $count = 0;
1459 foreach my $parameter (@{$args{'parameterlist'}}) {
1460 print ".br\n.BI \" $parameter\"\n";
1461 if ($count == $#{$args{'parameterlist'}}) {
1462 print "\n};\n";
1463 last;
1465 else {
1466 print ", \n.br\n";
1468 $count++;
1471 print ".SH Constants\n";
1472 foreach $parameter (@{$args{'parameterlist'}}) {
1473 my $parameter_name = $parameter;
1474 $parameter_name =~ s/\[.*//;
1476 print ".IP \"" . $parameter . "\" 12\n";
1477 output_highlight($args{'parameterdescs'}{$parameter_name});
1479 foreach $section (@{$args{'sectionlist'}}) {
1480 print ".SH \"$section\"\n";
1481 output_highlight($args{'sections'}{$section});
1486 # output struct in man
1487 sub output_struct_man(%) {
1488 my %args = %{$_[0]};
1489 my ($parameter, $section);
1491 print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";
1493 print ".SH NAME\n";
1494 print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
1496 print ".SH SYNOPSIS\n";
1497 print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
1499 foreach my $parameter (@{$args{'parameterlist'}}) {
1500 if ($parameter =~ /^#/) {
1501 print ".BI \"$parameter\"\n.br\n";
1502 next;
1504 my $parameter_name = $parameter;
1505 $parameter_name =~ s/\[.*//;
1507 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1508 $type = $args{'parametertypes'}{$parameter};
1509 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1510 # pointer-to-function
1511 print ".BI \" " . $1 . "\" " . $parameter . " \") (" . $2 . ")" . "\"\n;\n";
1512 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1513 # bitfield
1514 print ".BI \" " . $1 . "\ \" " . $parameter . $2 . " \"" . "\"\n;\n";
1515 } else {
1516 $type =~ s/([^\*])$/$1 /;
1517 print ".BI \" " . $type . "\" " . $parameter . " \"" . "\"\n;\n";
1519 print "\n.br\n";
1521 print "};\n.br\n";
1523 print ".SH Members\n";
1524 foreach $parameter (@{$args{'parameterlist'}}) {
1525 ($parameter =~ /^#/) && next;
1527 my $parameter_name = $parameter;
1528 $parameter_name =~ s/\[.*//;
1530 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1531 print ".IP \"" . $parameter . "\" 12\n";
1532 output_highlight($args{'parameterdescs'}{$parameter_name});
1534 foreach $section (@{$args{'sectionlist'}}) {
1535 print ".SH \"$section\"\n";
1536 output_highlight($args{'sections'}{$section});
1541 # output typedef in man
1542 sub output_typedef_man(%) {
1543 my %args = %{$_[0]};
1544 my ($parameter, $section);
1546 print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
1548 print ".SH NAME\n";
1549 print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
1551 foreach $section (@{$args{'sectionlist'}}) {
1552 print ".SH \"$section\"\n";
1553 output_highlight($args{'sections'}{$section});
1557 sub output_blockhead_man(%) {
1558 my %args = %{$_[0]};
1559 my ($parameter, $section);
1560 my $count;
1562 print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
1564 foreach $section (@{$args{'sectionlist'}}) {
1565 print ".SH \"$section\"\n";
1566 output_highlight($args{'sections'}{$section});
1571 # output in text
1572 sub output_function_text(%) {
1573 my %args = %{$_[0]};
1574 my ($parameter, $section);
1575 my $start;
1577 print "Name:\n\n";
1578 print $args{'function'} . " - " . $args{'purpose'} . "\n";
1580 print "\nSynopsis:\n\n";
1581 if ($args{'functiontype'} ne "") {
1582 $start = $args{'functiontype'} . " " . $args{'function'} . " (";
1583 } else {
1584 $start = $args{'function'} . " (";
1586 print $start;
1588 my $count = 0;
1589 foreach my $parameter (@{$args{'parameterlist'}}) {
1590 $type = $args{'parametertypes'}{$parameter};
1591 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1592 # pointer-to-function
1593 print $1 . $parameter . ") (" . $2;
1594 } else {
1595 print $type . " " . $parameter;
1597 if ($count != $#{$args{'parameterlist'}}) {
1598 $count++;
1599 print ",\n";
1600 print " " x length($start);
1601 } else {
1602 print ");\n\n";
1606 print "Arguments:\n\n";
1607 foreach $parameter (@{$args{'parameterlist'}}) {
1608 my $parameter_name = $parameter;
1609 $parameter_name =~ s/\[.*//;
1611 print $parameter . "\n\t" . $args{'parameterdescs'}{$parameter_name} . "\n";
1613 output_section_text(@_);
1616 #output sections in text
1617 sub output_section_text(%) {
1618 my %args = %{$_[0]};
1619 my $section;
1621 print "\n";
1622 foreach $section (@{$args{'sectionlist'}}) {
1623 print "$section:\n\n";
1624 output_highlight($args{'sections'}{$section});
1626 print "\n\n";
1629 # output enum in text
1630 sub output_enum_text(%) {
1631 my %args = %{$_[0]};
1632 my ($parameter);
1633 my $count;
1634 print "Enum:\n\n";
1636 print "enum " . $args{'enum'} . " - " . $args{'purpose'} . "\n\n";
1637 print "enum " . $args{'enum'} . " {\n";
1638 $count = 0;
1639 foreach $parameter (@{$args{'parameterlist'}}) {
1640 print "\t$parameter";
1641 if ($count != $#{$args{'parameterlist'}}) {
1642 $count++;
1643 print ",";
1645 print "\n";
1647 print "};\n\n";
1649 print "Constants:\n\n";
1650 foreach $parameter (@{$args{'parameterlist'}}) {
1651 print "$parameter\n\t";
1652 print $args{'parameterdescs'}{$parameter} . "\n";
1655 output_section_text(@_);
1658 # output typedef in text
1659 sub output_typedef_text(%) {
1660 my %args = %{$_[0]};
1661 my ($parameter);
1662 my $count;
1663 print "Typedef:\n\n";
1665 print "typedef " . $args{'typedef'} . " - " . $args{'purpose'} . "\n";
1666 output_section_text(@_);
1669 # output struct as text
1670 sub output_struct_text(%) {
1671 my %args = %{$_[0]};
1672 my ($parameter);
1674 print $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "\n\n";
1675 print $args{'type'} . " " . $args{'struct'} . " {\n";
1676 foreach $parameter (@{$args{'parameterlist'}}) {
1677 if ($parameter =~ /^#/) {
1678 print "$parameter\n";
1679 next;
1682 my $parameter_name = $parameter;
1683 $parameter_name =~ s/\[.*//;
1685 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1686 $type = $args{'parametertypes'}{$parameter};
1687 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1688 # pointer-to-function
1689 print "\t$1 $parameter) ($2);\n";
1690 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1691 # bitfield
1692 print "\t$1 $parameter$2;\n";
1693 } else {
1694 print "\t" . $type . " " . $parameter . ";\n";
1697 print "};\n\n";
1699 print "Members:\n\n";
1700 foreach $parameter (@{$args{'parameterlist'}}) {
1701 ($parameter =~ /^#/) && next;
1703 my $parameter_name = $parameter;
1704 $parameter_name =~ s/\[.*//;
1706 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1707 print "$parameter\n\t";
1708 print $args{'parameterdescs'}{$parameter_name} . "\n";
1710 print "\n";
1711 output_section_text(@_);
1714 sub output_blockhead_text(%) {
1715 my %args = %{$_[0]};
1716 my ($parameter, $section);
1718 foreach $section (@{$args{'sectionlist'}}) {
1719 print " $section:\n";
1720 print " -> ";
1721 output_highlight($args{'sections'}{$section});
1726 # output in restructured text
1730 # This could use some work; it's used to output the DOC: sections, and
1731 # starts by putting out the name of the doc section itself, but that tends
1732 # to duplicate a header already in the template file.
1734 sub output_blockhead_rst(%) {
1735 my %args = %{$_[0]};
1736 my ($parameter, $section);
1738 foreach $section (@{$args{'sectionlist'}}) {
1739 print "**$section**\n\n";
1740 output_highlight_rst($args{'sections'}{$section});
1741 print "\n";
1745 sub output_highlight_rst {
1746 my $contents = join "\n",@_;
1747 my $line;
1749 # undo the evil effects of xml_escape() earlier
1750 $contents = xml_unescape($contents);
1752 eval $dohighlight;
1753 die $@ if $@;
1755 foreach $line (split "\n", $contents) {
1756 if ($line eq "") {
1757 print $lineprefix, $blankline;
1758 } else {
1759 $line =~ s/\\\\\\/\&/g;
1760 print $lineprefix, $line;
1762 print "\n";
1766 sub output_function_rst(%) {
1767 my %args = %{$_[0]};
1768 my ($parameter, $section);
1769 my $start;
1771 print ".. c:function:: ";
1772 if ($args{'functiontype'} ne "") {
1773 $start = $args{'functiontype'} . " " . $args{'function'} . " (";
1774 } else {
1775 $start = $args{'function'} . " (";
1777 print $start;
1779 my $count = 0;
1780 foreach my $parameter (@{$args{'parameterlist'}}) {
1781 if ($count ne 0) {
1782 print ", ";
1784 $count++;
1785 $type = $args{'parametertypes'}{$parameter};
1786 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1787 # pointer-to-function
1788 print $1 . $parameter . ") (" . $2;
1789 } else {
1790 print $type . " " . $parameter;
1793 print ")\n\n " . $args{'purpose'} . "\n\n";
1795 print ":Parameters:\n\n";
1796 foreach $parameter (@{$args{'parameterlist'}}) {
1797 my $parameter_name = $parameter;
1798 #$parameter_name =~ s/\[.*//;
1799 $type = $args{'parametertypes'}{$parameter};
1801 if ($type ne "") {
1802 print " ``$type $parameter``\n";
1803 } else {
1804 print " ``$parameter``\n";
1806 if ($args{'parameterdescs'}{$parameter_name} ne $undescribed) {
1807 my $oldprefix = $lineprefix;
1808 $lineprefix = " ";
1809 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1810 $lineprefix = $oldprefix;
1811 } else {
1812 print "\n _undescribed_\n";
1814 print "\n";
1816 output_section_rst(@_);
1819 sub output_section_rst(%) {
1820 my %args = %{$_[0]};
1821 my $section;
1822 my $oldprefix = $lineprefix;
1823 $lineprefix = " ";
1825 foreach $section (@{$args{'sectionlist'}}) {
1826 print ":$section:\n\n";
1827 output_highlight_rst($args{'sections'}{$section});
1828 print "\n";
1830 print "\n";
1831 $lineprefix = $oldprefix;
1834 sub output_enum_rst(%) {
1835 my %args = %{$_[0]};
1836 my ($parameter);
1837 my $count;
1838 my $name = "enum " . $args{'enum'};
1840 print "\n\n.. c:type:: " . $name . "\n\n";
1841 print " " . $args{'purpose'} . "\n\n";
1843 print "..\n\n:Constants:\n\n";
1844 my $oldprefix = $lineprefix;
1845 $lineprefix = " ";
1846 foreach $parameter (@{$args{'parameterlist'}}) {
1847 print " `$parameter`\n";
1848 if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
1849 output_highlight_rst($args{'parameterdescs'}{$parameter});
1850 } else {
1851 print " undescribed\n";
1853 print "\n";
1855 $lineprefix = $oldprefix;
1856 output_section_rst(@_);
1859 sub output_typedef_rst(%) {
1860 my %args = %{$_[0]};
1861 my ($parameter);
1862 my $count;
1863 my $name = "typedef " . $args{'typedef'};
1865 ### FIXME: should the name below contain "typedef" or not?
1866 print "\n\n.. c:type:: " . $name . "\n\n";
1867 print " " . $args{'purpose'} . "\n\n";
1869 output_section_rst(@_);
1872 sub output_struct_rst(%) {
1873 my %args = %{$_[0]};
1874 my ($parameter);
1875 my $name = $args{'type'} . " " . $args{'struct'};
1877 print "\n\n.. c:type:: " . $name . "\n\n";
1878 print " " . $args{'purpose'} . "\n\n";
1880 print ":Definition:\n\n";
1881 print " ::\n\n";
1882 print " " . $args{'type'} . " " . $args{'struct'} . " {\n";
1883 foreach $parameter (@{$args{'parameterlist'}}) {
1884 if ($parameter =~ /^#/) {
1885 print " " . "$parameter\n";
1886 next;
1889 my $parameter_name = $parameter;
1890 $parameter_name =~ s/\[.*//;
1892 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1893 $type = $args{'parametertypes'}{$parameter};
1894 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1895 # pointer-to-function
1896 print " $1 $parameter) ($2);\n";
1897 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1898 # bitfield
1899 print " $1 $parameter$2;\n";
1900 } else {
1901 print " " . $type . " " . $parameter . ";\n";
1904 print " };\n\n";
1906 print ":Members:\n\n";
1907 foreach $parameter (@{$args{'parameterlist'}}) {
1908 ($parameter =~ /^#/) && next;
1910 my $parameter_name = $parameter;
1911 $parameter_name =~ s/\[.*//;
1913 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1914 $type = $args{'parametertypes'}{$parameter};
1915 print " `$type $parameter`" . "\n";
1916 my $oldprefix = $lineprefix;
1917 $lineprefix = " ";
1918 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1919 $lineprefix = $oldprefix;
1920 print "\n";
1922 print "\n";
1923 output_section_rst(@_);
1927 ## list mode output functions
1929 sub output_function_list(%) {
1930 my %args = %{$_[0]};
1932 print $args{'function'} . "\n";
1935 # output enum in list
1936 sub output_enum_list(%) {
1937 my %args = %{$_[0]};
1938 print $args{'enum'} . "\n";
1941 # output typedef in list
1942 sub output_typedef_list(%) {
1943 my %args = %{$_[0]};
1944 print $args{'typedef'} . "\n";
1947 # output struct as list
1948 sub output_struct_list(%) {
1949 my %args = %{$_[0]};
1951 print $args{'struct'} . "\n";
1954 sub output_blockhead_list(%) {
1955 my %args = %{$_[0]};
1956 my ($parameter, $section);
1958 foreach $section (@{$args{'sectionlist'}}) {
1959 print "DOC: $section\n";
1964 # generic output function for all types (function, struct/union, typedef, enum);
1965 # calls the generated, variable output_ function name based on
1966 # functype and output_mode
1967 sub output_declaration {
1968 no strict 'refs';
1969 my $name = shift;
1970 my $functype = shift;
1971 my $func = "output_${functype}_$output_mode";
1972 if (($function_only==0) ||
1973 ( $function_only == 1 && defined($function_table{$name})) ||
1974 ( $function_only == 2 && !($functype eq "function" && defined($function_table{$name}))))
1976 &$func(@_);
1977 $section_counter++;
1982 # generic output function - calls the right one based on current output mode.
1983 sub output_blockhead {
1984 no strict 'refs';
1985 my $func = "output_blockhead_" . $output_mode;
1986 &$func(@_);
1987 $section_counter++;
1991 # takes a declaration (struct, union, enum, typedef) and
1992 # invokes the right handler. NOT called for functions.
1993 sub dump_declaration($$) {
1994 no strict 'refs';
1995 my ($prototype, $file) = @_;
1996 my $func = "dump_" . $decl_type;
1997 &$func(@_);
2000 sub dump_union($$) {
2001 dump_struct(@_);
2004 sub dump_struct($$) {
2005 my $x = shift;
2006 my $file = shift;
2007 my $nested;
2009 if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
2010 #my $decl_type = $1;
2011 $declaration_name = $2;
2012 my $members = $3;
2014 # ignore embedded structs or unions
2015 $members =~ s/({.*})//g;
2016 $nested = $1;
2018 # ignore members marked private:
2019 $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
2020 $members =~ s/\/\*\s*private:.*//gosi;
2021 # strip comments:
2022 $members =~ s/\/\*.*?\*\///gos;
2023 $nested =~ s/\/\*.*?\*\///gos;
2024 # strip kmemcheck_bitfield_{begin,end}.*;
2025 $members =~ s/kmemcheck_bitfield_.*?;//gos;
2026 # strip attributes
2027 $members =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
2028 $members =~ s/__aligned\s*\([^;]*\)//gos;
2029 $members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos;
2030 # replace DECLARE_BITMAP
2031 $members =~ s/DECLARE_BITMAP\s*\(([^,)]+), ([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
2033 create_parameterlist($members, ';', $file);
2034 check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested);
2036 output_declaration($declaration_name,
2037 'struct',
2038 {'struct' => $declaration_name,
2039 'module' => $modulename,
2040 'parameterlist' => \@parameterlist,
2041 'parameterdescs' => \%parameterdescs,
2042 'parametertypes' => \%parametertypes,
2043 'sectionlist' => \@sectionlist,
2044 'sections' => \%sections,
2045 'purpose' => $declaration_purpose,
2046 'type' => $decl_type
2049 else {
2050 print STDERR "${file}:$.: error: Cannot parse struct or union!\n";
2051 ++$errors;
2055 sub dump_enum($$) {
2056 my $x = shift;
2057 my $file = shift;
2059 $x =~ s@/\*.*?\*/@@gos; # strip comments.
2060 # strip #define macros inside enums
2061 $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
2063 if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
2064 $declaration_name = $1;
2065 my $members = $2;
2067 foreach my $arg (split ',', $members) {
2068 $arg =~ s/^\s*(\w+).*/$1/;
2069 push @parameterlist, $arg;
2070 if (!$parameterdescs{$arg}) {
2071 $parameterdescs{$arg} = $undescribed;
2072 print STDERR "${file}:$.: warning: Enum value '$arg' ".
2073 "not described in enum '$declaration_name'\n";
2078 output_declaration($declaration_name,
2079 'enum',
2080 {'enum' => $declaration_name,
2081 'module' => $modulename,
2082 'parameterlist' => \@parameterlist,
2083 'parameterdescs' => \%parameterdescs,
2084 'sectionlist' => \@sectionlist,
2085 'sections' => \%sections,
2086 'purpose' => $declaration_purpose
2089 else {
2090 print STDERR "${file}:$.: error: Cannot parse enum!\n";
2091 ++$errors;
2095 sub dump_typedef($$) {
2096 my $x = shift;
2097 my $file = shift;
2099 $x =~ s@/\*.*?\*/@@gos; # strip comments.
2101 # Parse function prototypes
2102 if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/) {
2103 # Function typedefs
2104 $return_type = $1;
2105 $declaration_name = $2;
2106 my $args = $3;
2108 create_parameterlist($args, ',', $file);
2110 output_declaration($declaration_name,
2111 'function',
2112 {'function' => $declaration_name,
2113 'module' => $modulename,
2114 'functiontype' => $return_type,
2115 'parameterlist' => \@parameterlist,
2116 'parameterdescs' => \%parameterdescs,
2117 'parametertypes' => \%parametertypes,
2118 'sectionlist' => \@sectionlist,
2119 'sections' => \%sections,
2120 'purpose' => $declaration_purpose
2122 return;
2125 while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
2126 $x =~ s/\(*.\)\s*;$/;/;
2127 $x =~ s/\[*.\]\s*;$/;/;
2130 if ($x =~ /typedef.*\s+(\w+)\s*;/) {
2131 $declaration_name = $1;
2133 output_declaration($declaration_name,
2134 'typedef',
2135 {'typedef' => $declaration_name,
2136 'module' => $modulename,
2137 'sectionlist' => \@sectionlist,
2138 'sections' => \%sections,
2139 'purpose' => $declaration_purpose
2142 else {
2143 print STDERR "${file}:$.: error: Cannot parse typedef!\n";
2144 ++$errors;
2148 sub save_struct_actual($) {
2149 my $actual = shift;
2151 # strip all spaces from the actual param so that it looks like one string item
2152 $actual =~ s/\s*//g;
2153 $struct_actual = $struct_actual . $actual . " ";
2156 sub create_parameterlist($$$) {
2157 my $args = shift;
2158 my $splitter = shift;
2159 my $file = shift;
2160 my $type;
2161 my $param;
2163 # temporarily replace commas inside function pointer definition
2164 while ($args =~ /(\([^\),]+),/) {
2165 $args =~ s/(\([^\),]+),/$1#/g;
2168 foreach my $arg (split($splitter, $args)) {
2169 # strip comments
2170 $arg =~ s/\/\*.*\*\///;
2171 # strip leading/trailing spaces
2172 $arg =~ s/^\s*//;
2173 $arg =~ s/\s*$//;
2174 $arg =~ s/\s+/ /;
2176 if ($arg =~ /^#/) {
2177 # Treat preprocessor directive as a typeless variable just to fill
2178 # corresponding data structures "correctly". Catch it later in
2179 # output_* subs.
2180 push_parameter($arg, "", $file);
2181 } elsif ($arg =~ m/\(.+\)\s*\(/) {
2182 # pointer-to-function
2183 $arg =~ tr/#/,/;
2184 $arg =~ m/[^\(]+\(\*?\s*(\w*)\s*\)/;
2185 $param = $1;
2186 $type = $arg;
2187 $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
2188 save_struct_actual($param);
2189 push_parameter($param, $type, $file);
2190 } elsif ($arg) {
2191 $arg =~ s/\s*:\s*/:/g;
2192 $arg =~ s/\s*\[/\[/g;
2194 my @args = split('\s*,\s*', $arg);
2195 if ($args[0] =~ m/\*/) {
2196 $args[0] =~ s/(\*+)\s*/ $1/;
2199 my @first_arg;
2200 if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
2201 shift @args;
2202 push(@first_arg, split('\s+', $1));
2203 push(@first_arg, $2);
2204 } else {
2205 @first_arg = split('\s+', shift @args);
2208 unshift(@args, pop @first_arg);
2209 $type = join " ", @first_arg;
2211 foreach $param (@args) {
2212 if ($param =~ m/^(\*+)\s*(.*)/) {
2213 save_struct_actual($2);
2214 push_parameter($2, "$type $1", $file);
2216 elsif ($param =~ m/(.*?):(\d+)/) {
2217 if ($type ne "") { # skip unnamed bit-fields
2218 save_struct_actual($1);
2219 push_parameter($1, "$type:$2", $file)
2222 else {
2223 save_struct_actual($param);
2224 push_parameter($param, $type, $file);
2231 sub push_parameter($$$) {
2232 my $param = shift;
2233 my $type = shift;
2234 my $file = shift;
2236 if (($anon_struct_union == 1) && ($type eq "") &&
2237 ($param eq "}")) {
2238 return; # ignore the ending }; from anon. struct/union
2241 $anon_struct_union = 0;
2242 my $param_name = $param;
2243 $param_name =~ s/\[.*//;
2245 if ($type eq "" && $param =~ /\.\.\.$/)
2247 if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
2248 $parameterdescs{$param} = "variable arguments";
2251 elsif ($type eq "" && ($param eq "" or $param eq "void"))
2253 $param="void";
2254 $parameterdescs{void} = "no arguments";
2256 elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
2257 # handle unnamed (anonymous) union or struct:
2259 $type = $param;
2260 $param = "{unnamed_" . $param . "}";
2261 $parameterdescs{$param} = "anonymous\n";
2262 $anon_struct_union = 1;
2265 # warn if parameter has no description
2266 # (but ignore ones starting with # as these are not parameters
2267 # but inline preprocessor statements);
2268 # also ignore unnamed structs/unions;
2269 if (!$anon_struct_union) {
2270 if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {
2272 $parameterdescs{$param_name} = $undescribed;
2274 if (($type eq 'function') || ($type eq 'enum')) {
2275 print STDERR "${file}:$.: warning: Function parameter ".
2276 "or member '$param' not " .
2277 "described in '$declaration_name'\n";
2279 print STDERR "${file}:$.: warning:" .
2280 " No description found for parameter '$param'\n";
2281 ++$warnings;
2285 $param = xml_escape($param);
2287 # strip spaces from $param so that it is one continuous string
2288 # on @parameterlist;
2289 # this fixes a problem where check_sections() cannot find
2290 # a parameter like "addr[6 + 2]" because it actually appears
2291 # as "addr[6", "+", "2]" on the parameter list;
2292 # but it's better to maintain the param string unchanged for output,
2293 # so just weaken the string compare in check_sections() to ignore
2294 # "[blah" in a parameter string;
2295 ###$param =~ s/\s*//g;
2296 push @parameterlist, $param;
2297 $parametertypes{$param} = $type;
2300 sub check_sections($$$$$$) {
2301 my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck, $nested) = @_;
2302 my @sects = split ' ', $sectcheck;
2303 my @prms = split ' ', $prmscheck;
2304 my $err;
2305 my ($px, $sx);
2306 my $prm_clean; # strip trailing "[array size]" and/or beginning "*"
2308 foreach $sx (0 .. $#sects) {
2309 $err = 1;
2310 foreach $px (0 .. $#prms) {
2311 $prm_clean = $prms[$px];
2312 $prm_clean =~ s/\[.*\]//;
2313 $prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
2314 # ignore array size in a parameter string;
2315 # however, the original param string may contain
2316 # spaces, e.g.: addr[6 + 2]
2317 # and this appears in @prms as "addr[6" since the
2318 # parameter list is split at spaces;
2319 # hence just ignore "[..." for the sections check;
2320 $prm_clean =~ s/\[.*//;
2322 ##$prm_clean =~ s/^\**//;
2323 if ($prm_clean eq $sects[$sx]) {
2324 $err = 0;
2325 last;
2328 if ($err) {
2329 if ($decl_type eq "function") {
2330 print STDERR "${file}:$.: warning: " .
2331 "Excess function parameter " .
2332 "'$sects[$sx]' " .
2333 "description in '$decl_name'\n";
2334 ++$warnings;
2335 } else {
2336 if ($nested !~ m/\Q$sects[$sx]\E/) {
2337 print STDERR "${file}:$.: warning: " .
2338 "Excess struct/union/enum/typedef member " .
2339 "'$sects[$sx]' " .
2340 "description in '$decl_name'\n";
2341 ++$warnings;
2349 # Checks the section describing the return value of a function.
2350 sub check_return_section {
2351 my $file = shift;
2352 my $declaration_name = shift;
2353 my $return_type = shift;
2355 # Ignore an empty return type (It's a macro)
2356 # Ignore functions with a "void" return type. (But don't ignore "void *")
2357 if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
2358 return;
2361 if (!defined($sections{$section_return}) ||
2362 $sections{$section_return} eq "") {
2363 print STDERR "${file}:$.: warning: " .
2364 "No description found for return value of " .
2365 "'$declaration_name'\n";
2366 ++$warnings;
2371 # takes a function prototype and the name of the current file being
2372 # processed and spits out all the details stored in the global
2373 # arrays/hashes.
2374 sub dump_function($$) {
2375 my $prototype = shift;
2376 my $file = shift;
2377 my $noret = 0;
2379 $prototype =~ s/^static +//;
2380 $prototype =~ s/^extern +//;
2381 $prototype =~ s/^asmlinkage +//;
2382 $prototype =~ s/^inline +//;
2383 $prototype =~ s/^__inline__ +//;
2384 $prototype =~ s/^__inline +//;
2385 $prototype =~ s/^__always_inline +//;
2386 $prototype =~ s/^noinline +//;
2387 $prototype =~ s/__init +//;
2388 $prototype =~ s/__init_or_module +//;
2389 $prototype =~ s/__meminit +//;
2390 $prototype =~ s/__must_check +//;
2391 $prototype =~ s/__weak +//;
2392 my $define = $prototype =~ s/^#\s*define\s+//; #ak added
2393 $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
2395 # Yes, this truly is vile. We are looking for:
2396 # 1. Return type (may be nothing if we're looking at a macro)
2397 # 2. Function name
2398 # 3. Function parameters.
2400 # All the while we have to watch out for function pointer parameters
2401 # (which IIRC is what the two sections are for), C types (these
2402 # regexps don't even start to express all the possibilities), and
2403 # so on.
2405 # If you mess with these regexps, it's a good idea to check that
2406 # the following functions' documentation still comes out right:
2407 # - parport_register_device (function pointer parameters)
2408 # - atomic_set (macro)
2409 # - pci_match_device, __copy_to_user (long return type)
2411 if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) {
2412 # This is an object-like macro, it has no return type and no parameter
2413 # list.
2414 # Function-like macros are not allowed to have spaces between
2415 # declaration_name and opening parenthesis (notice the \s+).
2416 $return_type = $1;
2417 $declaration_name = $2;
2418 $noret = 1;
2419 } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2420 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2421 $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2422 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2423 $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2424 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2425 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2426 $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2427 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2428 $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2429 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2430 $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2431 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2432 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2433 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2434 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2435 $prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) {
2436 $return_type = $1;
2437 $declaration_name = $2;
2438 my $args = $3;
2440 create_parameterlist($args, ',', $file);
2441 } else {
2442 print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
2443 return;
2446 my $prms = join " ", @parameterlist;
2447 check_sections($file, $declaration_name, "function", $sectcheck, $prms, "");
2449 # This check emits a lot of warnings at the moment, because many
2450 # functions don't have a 'Return' doc section. So until the number
2451 # of warnings goes sufficiently down, the check is only performed in
2452 # verbose mode.
2453 # TODO: always perform the check.
2454 if ($verbose && !$noret) {
2455 check_return_section($file, $declaration_name, $return_type);
2458 output_declaration($declaration_name,
2459 'function',
2460 {'function' => $declaration_name,
2461 'module' => $modulename,
2462 'functiontype' => $return_type,
2463 'parameterlist' => \@parameterlist,
2464 'parameterdescs' => \%parameterdescs,
2465 'parametertypes' => \%parametertypes,
2466 'sectionlist' => \@sectionlist,
2467 'sections' => \%sections,
2468 'purpose' => $declaration_purpose
2472 sub reset_state {
2473 $function = "";
2474 %constants = ();
2475 %parameterdescs = ();
2476 %parametertypes = ();
2477 @parameterlist = ();
2478 %sections = ();
2479 @sectionlist = ();
2480 $sectcheck = "";
2481 $struct_actual = "";
2482 $prototype = "";
2484 $state = 0;
2485 $split_doc_state = 0;
2488 sub tracepoint_munge($) {
2489 my $file = shift;
2490 my $tracepointname = 0;
2491 my $tracepointargs = 0;
2493 if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
2494 $tracepointname = $1;
2496 if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
2497 $tracepointname = $1;
2499 if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
2500 $tracepointname = $2;
2502 $tracepointname =~ s/^\s+//; #strip leading whitespace
2503 if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
2504 $tracepointargs = $1;
2506 if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
2507 print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
2508 "$prototype\n";
2509 } else {
2510 $prototype = "static inline void trace_$tracepointname($tracepointargs)";
2514 sub syscall_munge() {
2515 my $void = 0;
2517 $prototype =~ s@[\r\n\t]+@ @gos; # strip newlines/CR's/tabs
2518 ## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
2519 if ($prototype =~ m/SYSCALL_DEFINE0/) {
2520 $void = 1;
2521 ## $prototype = "long sys_$1(void)";
2524 $prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
2525 if ($prototype =~ m/long (sys_.*?),/) {
2526 $prototype =~ s/,/\(/;
2527 } elsif ($void) {
2528 $prototype =~ s/\)/\(void\)/;
2531 # now delete all of the odd-number commas in $prototype
2532 # so that arg types & arg names don't have a comma between them
2533 my $count = 0;
2534 my $len = length($prototype);
2535 if ($void) {
2536 $len = 0; # skip the for-loop
2538 for (my $ix = 0; $ix < $len; $ix++) {
2539 if (substr($prototype, $ix, 1) eq ',') {
2540 $count++;
2541 if ($count % 2 == 1) {
2542 substr($prototype, $ix, 1) = ' ';
2548 sub process_state3_function($$) {
2549 my $x = shift;
2550 my $file = shift;
2552 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2554 if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
2555 # do nothing
2557 elsif ($x =~ /([^\{]*)/) {
2558 $prototype .= $1;
2561 if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
2562 $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
2563 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2564 $prototype =~ s@^\s+@@gos; # strip leading spaces
2565 if ($prototype =~ /SYSCALL_DEFINE/) {
2566 syscall_munge();
2568 if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
2569 $prototype =~ /DEFINE_SINGLE_EVENT/)
2571 tracepoint_munge($file);
2573 dump_function($prototype, $file);
2574 reset_state();
2578 sub process_state3_type($$) {
2579 my $x = shift;
2580 my $file = shift;
2582 $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2583 $x =~ s@^\s+@@gos; # strip leading spaces
2584 $x =~ s@\s+$@@gos; # strip trailing spaces
2585 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2587 if ($x =~ /^#/) {
2588 # To distinguish preprocessor directive from regular declaration later.
2589 $x .= ";";
2592 while (1) {
2593 if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
2594 $prototype .= $1 . $2;
2595 ($2 eq '{') && $brcount++;
2596 ($2 eq '}') && $brcount--;
2597 if (($2 eq ';') && ($brcount == 0)) {
2598 dump_declaration($prototype, $file);
2599 reset_state();
2600 last;
2602 $x = $3;
2603 } else {
2604 $prototype .= $x;
2605 last;
2610 # xml_escape: replace <, >, and & in the text stream;
2612 # however, formatting controls that are generated internally/locally in the
2613 # kernel-doc script are not escaped here; instead, they begin life like
2614 # $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
2615 # are converted to their mnemonic-expected output, without the 4 * '\' & ':',
2616 # just before actual output; (this is done by local_unescape())
2617 sub xml_escape($) {
2618 my $text = shift;
2619 if (($output_mode eq "text") || ($output_mode eq "man")) {
2620 return $text;
2622 $text =~ s/\&/\\\\\\amp;/g;
2623 $text =~ s/\</\\\\\\lt;/g;
2624 $text =~ s/\>/\\\\\\gt;/g;
2625 return $text;
2628 # xml_unescape: reverse the effects of xml_escape
2629 sub xml_unescape($) {
2630 my $text = shift;
2631 if (($output_mode eq "text") || ($output_mode eq "man")) {
2632 return $text;
2634 $text =~ s/\\\\\\amp;/\&/g;
2635 $text =~ s/\\\\\\lt;/</g;
2636 $text =~ s/\\\\\\gt;/>/g;
2637 return $text;
2640 # convert local escape strings to html
2641 # local escape strings look like: '\\\\menmonic:' (that's 4 backslashes)
2642 sub local_unescape($) {
2643 my $text = shift;
2644 if (($output_mode eq "text") || ($output_mode eq "man")) {
2645 return $text;
2647 $text =~ s/\\\\\\\\lt:/</g;
2648 $text =~ s/\\\\\\\\gt:/>/g;
2649 return $text;
2652 sub process_file($) {
2653 my $file;
2654 my $identifier;
2655 my $func;
2656 my $descr;
2657 my $in_purpose = 0;
2658 my $initial_section_counter = $section_counter;
2659 my ($orig_file) = @_;
2661 if (defined($ENV{'SRCTREE'})) {
2662 $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
2664 else {
2665 $file = $orig_file;
2667 if (defined($source_map{$file})) {
2668 $file = $source_map{$file};
2671 if (!open(IN,"<$file")) {
2672 print STDERR "Error: Cannot open file $file\n";
2673 ++$errors;
2674 return;
2677 $. = 1;
2679 $section_counter = 0;
2680 while (<IN>) {
2681 while (s/\\\s*$//) {
2682 $_ .= <IN>;
2684 if ($state == 0) {
2685 if (/$doc_start/o) {
2686 $state = 1; # next line is always the function name
2687 $in_doc_sect = 0;
2689 } elsif ($state == 1) { # this line is the function name (always)
2690 if (/$doc_block/o) {
2691 $state = 4;
2692 $contents = "";
2693 if ( $1 eq "" ) {
2694 $section = $section_intro;
2695 } else {
2696 $section = $1;
2699 elsif (/$doc_decl/o) {
2700 $identifier = $1;
2701 if (/\s*([\w\s]+?)\s*-/) {
2702 $identifier = $1;
2705 $state = 2;
2706 if (/-(.*)/) {
2707 # strip leading/trailing/multiple spaces
2708 $descr= $1;
2709 $descr =~ s/^\s*//;
2710 $descr =~ s/\s*$//;
2711 $descr =~ s/\s+/ /g;
2712 $declaration_purpose = xml_escape($descr);
2713 $in_purpose = 1;
2714 } else {
2715 $declaration_purpose = "";
2718 if (($declaration_purpose eq "") && $verbose) {
2719 print STDERR "${file}:$.: warning: missing initial short description on line:\n";
2720 print STDERR $_;
2721 ++$warnings;
2724 if ($identifier =~ m/^struct/) {
2725 $decl_type = 'struct';
2726 } elsif ($identifier =~ m/^union/) {
2727 $decl_type = 'union';
2728 } elsif ($identifier =~ m/^enum/) {
2729 $decl_type = 'enum';
2730 } elsif ($identifier =~ m/^typedef/) {
2731 $decl_type = 'typedef';
2732 } else {
2733 $decl_type = 'function';
2736 if ($verbose) {
2737 print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
2739 } else {
2740 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
2741 " - I thought it was a doc line\n";
2742 ++$warnings;
2743 $state = 0;
2745 } elsif ($state == 2) { # look for head: lines, and include content
2746 if (/$doc_sect/o) {
2747 $newsection = $1;
2748 $newcontents = $2;
2750 if (($contents ne "") && ($contents ne "\n")) {
2751 if (!$in_doc_sect && $verbose) {
2752 print STDERR "${file}:$.: warning: contents before sections\n";
2753 ++$warnings;
2755 dump_section($file, $section, xml_escape($contents));
2756 $section = $section_default;
2759 $in_doc_sect = 1;
2760 $in_purpose = 0;
2761 $contents = $newcontents;
2762 if ($contents ne "") {
2763 while ((substr($contents, 0, 1) eq " ") ||
2764 substr($contents, 0, 1) eq "\t") {
2765 $contents = substr($contents, 1);
2767 $contents .= "\n";
2769 $section = $newsection;
2770 } elsif (/$doc_end/) {
2771 if (($contents ne "") && ($contents ne "\n")) {
2772 dump_section($file, $section, xml_escape($contents));
2773 $section = $section_default;
2774 $contents = "";
2776 # look for doc_com + <text> + doc_end:
2777 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2778 print STDERR "${file}:$.: warning: suspicious ending line: $_";
2779 ++$warnings;
2782 $prototype = "";
2783 $state = 3;
2784 $brcount = 0;
2785 # print STDERR "end of doc comment, looking for prototype\n";
2786 } elsif (/$doc_content/) {
2787 # miguel-style comment kludge, look for blank lines after
2788 # @parameter line to signify start of description
2789 if ($1 eq "") {
2790 if ($section =~ m/^@/ || $section eq $section_context) {
2791 dump_section($file, $section, xml_escape($contents));
2792 $section = $section_default;
2793 $contents = "";
2794 } else {
2795 $contents .= "\n";
2797 $in_purpose = 0;
2798 } elsif ($in_purpose == 1) {
2799 # Continued declaration purpose
2800 chomp($declaration_purpose);
2801 $declaration_purpose .= " " . xml_escape($1);
2802 $declaration_purpose =~ s/\s+/ /g;
2803 } else {
2804 $contents .= $1 . "\n";
2806 } else {
2807 # i dont know - bad line? ignore.
2808 print STDERR "${file}:$.: warning: bad line: $_";
2809 ++$warnings;
2811 } elsif ($state == 5) { # scanning for split parameters
2812 # First line (state 1) needs to be a @parameter
2813 if ($split_doc_state == 1 && /$doc_split_sect/o) {
2814 $section = $1;
2815 $contents = $2;
2816 if ($contents ne "") {
2817 while ((substr($contents, 0, 1) eq " ") ||
2818 substr($contents, 0, 1) eq "\t") {
2819 $contents = substr($contents, 1);
2821 $contents .= "\n";
2823 $split_doc_state = 2;
2824 # Documentation block end */
2825 } elsif (/$doc_split_end/) {
2826 if (($contents ne "") && ($contents ne "\n")) {
2827 dump_section($file, $section, xml_escape($contents));
2828 $section = $section_default;
2829 $contents = "";
2831 $state = 3;
2832 $split_doc_state = 0;
2833 # Regular text
2834 } elsif (/$doc_content/) {
2835 if ($split_doc_state == 2) {
2836 $contents .= $1 . "\n";
2837 } elsif ($split_doc_state == 1) {
2838 $split_doc_state = 4;
2839 print STDERR "Warning(${file}:$.): ";
2840 print STDERR "Incorrect use of kernel-doc format: $_";
2841 ++$warnings;
2844 } elsif ($state == 3) { # scanning for function '{' (end of prototype)
2845 if (/$doc_split_start/) {
2846 $state = 5;
2847 $split_doc_state = 1;
2848 } elsif ($decl_type eq 'function') {
2849 process_state3_function($_, $file);
2850 } else {
2851 process_state3_type($_, $file);
2853 } elsif ($state == 4) {
2854 # Documentation block
2855 if (/$doc_block/) {
2856 dump_doc_section($file, $section, xml_escape($contents));
2857 $contents = "";
2858 $function = "";
2859 %constants = ();
2860 %parameterdescs = ();
2861 %parametertypes = ();
2862 @parameterlist = ();
2863 %sections = ();
2864 @sectionlist = ();
2865 $prototype = "";
2866 if ( $1 eq "" ) {
2867 $section = $section_intro;
2868 } else {
2869 $section = $1;
2872 elsif (/$doc_end/)
2874 dump_doc_section($file, $section, xml_escape($contents));
2875 $contents = "";
2876 $function = "";
2877 %constants = ();
2878 %parameterdescs = ();
2879 %parametertypes = ();
2880 @parameterlist = ();
2881 %sections = ();
2882 @sectionlist = ();
2883 $prototype = "";
2884 $state = 0;
2886 elsif (/$doc_content/)
2888 if ( $1 eq "" )
2890 $contents .= $blankline;
2892 else
2894 $contents .= $1 . "\n";
2899 if ($initial_section_counter == $section_counter) {
2900 print STDERR "${file}:1: warning: no structured comments found\n";
2901 if (($function_only == 1) && ($show_not_found == 1)) {
2902 print STDERR " Was looking for '$_'.\n" for keys %function_table;
2904 if ($output_mode eq "xml") {
2905 # The template wants at least one RefEntry here; make one.
2906 print "<refentry>\n";
2907 print " <refnamediv>\n";
2908 print " <refname>\n";
2909 print " ${orig_file}\n";
2910 print " </refname>\n";
2911 print " <refpurpose>\n";
2912 print " Document generation inconsistency\n";
2913 print " </refpurpose>\n";
2914 print " </refnamediv>\n";
2915 print " <refsect1>\n";
2916 print " <title>\n";
2917 print " Oops\n";
2918 print " </title>\n";
2919 print " <warning>\n";
2920 print " <para>\n";
2921 print " The template for this document tried to insert\n";
2922 print " the structured comment from the file\n";
2923 print " <filename>${orig_file}</filename> at this point,\n";
2924 print " but none was found.\n";
2925 print " This dummy section is inserted to allow\n";
2926 print " generation to continue.\n";
2927 print " </para>\n";
2928 print " </warning>\n";
2929 print " </refsect1>\n";
2930 print "</refentry>\n";
2936 $kernelversion = get_kernel_version();
2938 # generate a sequence of code that will splice in highlighting information
2939 # using the s// operator.
2940 for (my $k = 0; $k < @highlights; $k++) {
2941 my $pattern = $highlights[$k][0];
2942 my $result = $highlights[$k][1];
2943 # print STDERR "scanning pattern:$pattern, highlight:($result)\n";
2944 $dohighlight .= "\$contents =~ s:$pattern:$result:gs;\n";
2947 # Read the file that maps relative names to absolute names for
2948 # separate source and object directories and for shadow trees.
2949 if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
2950 my ($relname, $absname);
2951 while(<SOURCE_MAP>) {
2952 chop();
2953 ($relname, $absname) = (split())[0..1];
2954 $relname =~ s:^/+::;
2955 $source_map{$relname} = $absname;
2957 close(SOURCE_MAP);
2960 foreach (@ARGV) {
2961 chomp;
2962 process_file($_);
2964 if ($verbose && $errors) {
2965 print STDERR "$errors errors\n";
2967 if ($verbose && $warnings) {
2968 print STDERR "$warnings warnings\n";
2971 exit($errors);