generic: add __FINITDATA
[wrt350n-kernel.git] / scripts / kernel-doc
blobec54f12f57b04c10b6f24f7aa561afccb3fba0b7
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-2007 Randy Dunlap ##
9 ## ##
10 ## #define enhancements by Armin Kuster <akuster@mvista.com> ##
11 ## Copyright (c) 2000 MontaVista Software, Inc. ##
12 ## ##
13 ## This software falls under the GNU General Public License. ##
14 ## Please read the COPYING file for more information ##
16 # w.o. 03-11-2000: added the '-filelist' option.
18 # 18/01/2001 - Cleanups
19 # Functions prototyped as foo(void) same as foo()
20 # Stop eval'ing where we don't need to.
21 # -- huggie@earth.li
23 # 27/06/2001 - Allowed whitespace after initial "/**" and
24 # allowed comments before function declarations.
25 # -- Christian Kreibich <ck@whoop.org>
27 # Still to do:
28 # - add perldoc documentation
29 # - Look more closely at some of the scarier bits :)
31 # 26/05/2001 - Support for separate source and object trees.
32 # Return error code.
33 # Keith Owens <kaos@ocs.com.au>
35 # 23/09/2001 - Added support for typedefs, structs, enums and unions
36 # Support for Context section; can be terminated using empty line
37 # Small fixes (like spaces vs. \s in regex)
38 # -- Tim Jansen <tim@tjansen.de>
42 # This will read a 'c' file and scan for embedded comments in the
43 # style of gnome comments (+minor extensions - see below).
46 # Note: This only supports 'c'.
48 # usage:
49 # kernel-doc [ -docbook | -html | -text | -man ] [ -no-doc-sections ]
50 # [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
51 # or
52 # [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile
54 # Set output format using one of -docbook -html -text or -man. Default is man.
56 # -no-doc-sections
57 # Do not output DOC: sections
59 # -function funcname
60 # If set, then only generate documentation for the given function(s) or
61 # DOC: section titles. All other functions and DOC: sections are ignored.
63 # -nofunction funcname
64 # If set, then only generate documentation for the other function(s)/DOC:
65 # sections. Cannot be used together with -function (yes, that's a bug --
66 # perl hackers can fix it 8))
68 # c files - list of 'c' files to process
70 # All output goes to stdout, with errors to stderr.
73 # format of comments.
74 # In the following table, (...)? signifies optional structure.
75 # (...)* signifies 0 or more structure elements
76 # /**
77 # * function_name(:)? (- short description)?
78 # (* @parameterx: (description of parameter x)?)*
79 # (* a blank line)?
80 # * (Description:)? (Description of function)?
81 # * (section header: (section description)? )*
82 # (*)?*/
84 # So .. the trivial example would be:
86 # /**
87 # * my_function
88 # **/
90 # If the Description: header tag is omitted, then there must be a blank line
91 # after the last parameter specification.
92 # e.g.
93 # /**
94 # * my_function - does my stuff
95 # * @my_arg: its mine damnit
96 # *
97 # * Does my stuff explained.
98 # */
100 # or, could also use:
101 # /**
102 # * my_function - does my stuff
103 # * @my_arg: its mine damnit
104 # * Description: Does my stuff explained.
105 # */
106 # etc.
108 # Beside functions you can also write documentation for structs, unions,
109 # enums and typedefs. Instead of the function name you must write the name
110 # of the declaration; the struct/union/enum/typedef must always precede
111 # the name. Nesting of declarations is not supported.
112 # Use the argument mechanism to document members or constants.
113 # e.g.
114 # /**
115 # * struct my_struct - short description
116 # * @a: first member
117 # * @b: second member
119 # * Longer description
120 # */
121 # struct my_struct {
122 # int a;
123 # int b;
124 # /* private: */
125 # int c;
126 # };
128 # All descriptions can be multiline, except the short function description.
130 # You can also add additional sections. When documenting kernel functions you
131 # should document the "Context:" of the function, e.g. whether the functions
132 # can be called form interrupts. Unlike other sections you can end it with an
133 # empty line.
134 # Example-sections should contain the string EXAMPLE so that they are marked
135 # appropriately in DocBook.
137 # Example:
138 # /**
139 # * user_function - function that can only be called in user context
140 # * @a: some argument
141 # * Context: !in_interrupt()
143 # * Some description
144 # * Example:
145 # * user_function(22);
146 # */
147 # ...
150 # All descriptive text is further processed, scanning for the following special
151 # patterns, which are highlighted appropriately.
153 # 'funcname()' - function
154 # '$ENVVAR' - environmental variable
155 # '&struct_name' - name of a structure (up to two words including 'struct')
156 # '@parameter' - name of a parameter
157 # '%CONST' - name of a constant.
159 my $errors = 0;
160 my $warnings = 0;
161 my $anon_struct_union = 0;
163 # match expressions used to find embedded type information
164 my $type_constant = '\%([-_\w]+)';
165 my $type_func = '(\w+)\(\)';
166 my $type_param = '\@(\w+)';
167 my $type_struct = '\&((struct\s*)*[_\w]+)';
168 my $type_struct_xml = '\\&amp;((struct\s*)*[_\w]+)';
169 my $type_env = '(\$\w+)';
171 # Output conversion substitutions.
172 # One for each output format
174 # these work fairly well
175 my %highlights_html = ( $type_constant, "<i>\$1</i>",
176 $type_func, "<b>\$1</b>",
177 $type_struct_xml, "<i>\$1</i>",
178 $type_env, "<b><i>\$1</i></b>",
179 $type_param, "<tt><b>\$1</b></tt>" );
180 my $local_lt = "\\\\\\\\lt:";
181 my $local_gt = "\\\\\\\\gt:";
182 my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>"
184 # XML, docbook format
185 my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
186 $type_constant, "<constant>\$1</constant>",
187 $type_func, "<function>\$1</function>",
188 $type_struct_xml, "<structname>\$1</structname>",
189 $type_env, "<envar>\$1</envar>",
190 $type_param, "<parameter>\$1</parameter>" );
191 my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
193 # gnome, docbook format
194 my %highlights_gnome = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",
195 $type_func, "<function>\$1</function>",
196 $type_struct, "<structname>\$1</structname>",
197 $type_env, "<envar>\$1</envar>",
198 $type_param, "<parameter>\$1</parameter>" );
199 my $blankline_gnome = "</para><para>\n";
201 # these are pretty rough
202 my %highlights_man = ( $type_constant, "\$1",
203 $type_func, "\\\\fB\$1\\\\fP",
204 $type_struct, "\\\\fI\$1\\\\fP",
205 $type_param, "\\\\fI\$1\\\\fP" );
206 my $blankline_man = "";
208 # text-mode
209 my %highlights_text = ( $type_constant, "\$1",
210 $type_func, "\$1",
211 $type_struct, "\$1",
212 $type_param, "\$1" );
213 my $blankline_text = "";
216 sub usage {
217 print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ] [ -no-doc-sections ]\n";
218 print " [ -function funcname [ -function funcname ...] ]\n";
219 print " [ -nofunction funcname [ -nofunction funcname ...] ]\n";
220 print " c source file(s) > outputfile\n";
221 exit 1;
224 # read arguments
225 if ($#ARGV==-1) {
226 usage();
229 my $verbose = 0;
230 my $output_mode = "man";
231 my $no_doc_sections = 0;
232 my %highlights = %highlights_man;
233 my $blankline = $blankline_man;
234 my $modulename = "Kernel API";
235 my $function_only = 0;
236 my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
237 'July', 'August', 'September', 'October',
238 'November', 'December')[(localtime)[4]] .
239 " " . ((localtime)[5]+1900);
241 # Essentially these are globals
242 # They probably want to be tidied up made more localised or summat.
243 # CAVEAT EMPTOR! Some of the others I localised may not want to be which
244 # could cause "use of undefined value" or other bugs.
245 my ($function, %function_table,%parametertypes,$declaration_purpose);
246 my ($type,$declaration_name,$return_type);
247 my ($newsection,$newcontents,$prototype,$filelist, $brcount, %source_map);
249 # Generated docbook code is inserted in a template at a point where
250 # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
251 # http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
252 # We keep track of number of generated entries and generate a dummy
253 # if needs be to ensure the expanded template can be postprocessed
254 # into html.
255 my $section_counter = 0;
257 my $lineprefix="";
259 # states
260 # 0 - normal code
261 # 1 - looking for function name
262 # 2 - scanning field start.
263 # 3 - scanning prototype.
264 # 4 - documentation block
265 my $state;
266 my $in_doc_sect;
268 #declaration types: can be
269 # 'function', 'struct', 'union', 'enum', 'typedef'
270 my $decl_type;
272 my $doc_special = "\@\%\$\&";
274 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
275 my $doc_end = '\*/';
276 my $doc_com = '\s*\*\s*';
277 my $doc_decl = $doc_com.'(\w+)';
278 my $doc_sect = $doc_com.'(['.$doc_special.']?[\w\s]+):(.*)';
279 my $doc_content = $doc_com.'(.*)';
280 my $doc_block = $doc_com.'DOC:\s*(.*)?';
282 my %constants;
283 my %parameterdescs;
284 my @parameterlist;
285 my %sections;
286 my @sectionlist;
288 my $contents = "";
289 my $section_default = "Description"; # default section
290 my $section_intro = "Introduction";
291 my $section = $section_default;
292 my $section_context = "Context";
294 my $undescribed = "-- undescribed --";
296 reset_state();
298 while ($ARGV[0] =~ m/^-(.*)/) {
299 my $cmd = shift @ARGV;
300 if ($cmd eq "-html") {
301 $output_mode = "html";
302 %highlights = %highlights_html;
303 $blankline = $blankline_html;
304 } elsif ($cmd eq "-man") {
305 $output_mode = "man";
306 %highlights = %highlights_man;
307 $blankline = $blankline_man;
308 } elsif ($cmd eq "-text") {
309 $output_mode = "text";
310 %highlights = %highlights_text;
311 $blankline = $blankline_text;
312 } elsif ($cmd eq "-docbook") {
313 $output_mode = "xml";
314 %highlights = %highlights_xml;
315 $blankline = $blankline_xml;
316 } elsif ($cmd eq "-gnome") {
317 $output_mode = "gnome";
318 %highlights = %highlights_gnome;
319 $blankline = $blankline_gnome;
320 } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
321 $modulename = shift @ARGV;
322 } elsif ($cmd eq "-function") { # to only output specific functions
323 $function_only = 1;
324 $function = shift @ARGV;
325 $function_table{$function} = 1;
326 } elsif ($cmd eq "-nofunction") { # to only output specific functions
327 $function_only = 2;
328 $function = shift @ARGV;
329 $function_table{$function} = 1;
330 } elsif ($cmd eq "-v") {
331 $verbose = 1;
332 } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
333 usage();
334 } elsif ($cmd eq '-filelist') {
335 $filelist = shift @ARGV;
336 } elsif ($cmd eq '-no-doc-sections') {
337 $no_doc_sections = 1;
341 # get kernel version from env
342 sub get_kernel_version() {
343 my $version = 'unknown kernel version';
345 if (defined($ENV{'KERNELVERSION'})) {
346 $version = $ENV{'KERNELVERSION'};
348 return $version;
350 my $kernelversion = get_kernel_version();
352 # generate a sequence of code that will splice in highlighting information
353 # using the s// operator.
354 my $dohighlight = "";
355 foreach my $pattern (keys %highlights) {
356 # print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n";
357 $dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
361 # dumps section contents to arrays/hashes intended for that purpose.
363 sub dump_section {
364 my $name = shift;
365 my $contents = join "\n", @_;
367 if ($name =~ m/$type_constant/) {
368 $name = $1;
369 # print STDERR "constant section '$1' = '$contents'\n";
370 $constants{$name} = $contents;
371 } elsif ($name =~ m/$type_param/) {
372 # print STDERR "parameter def '$1' = '$contents'\n";
373 $name = $1;
374 $parameterdescs{$name} = $contents;
375 } else {
376 # print STDERR "other section '$name' = '$contents'\n";
377 $sections{$name} = $contents;
378 push @sectionlist, $name;
383 # dump DOC: section after checking that it should go out
385 sub dump_doc_section {
386 my $name = shift;
387 my $contents = join "\n", @_;
389 if ($no_doc_sections) {
390 return;
393 if (($function_only == 0) ||
394 ( $function_only == 1 && defined($function_table{$name})) ||
395 ( $function_only == 2 && !defined($function_table{$name})))
397 dump_section $name, $contents;
398 output_blockhead({'sectionlist' => \@sectionlist,
399 'sections' => \%sections,
400 'module' => $modulename,
401 'content-only' => ($function_only != 0), });
406 # output function
408 # parameterdescs, a hash.
409 # function => "function name"
410 # parameterlist => @list of parameters
411 # parameterdescs => %parameter descriptions
412 # sectionlist => @list of sections
413 # sections => %section descriptions
416 sub output_highlight {
417 my $contents = join "\n",@_;
418 my $line;
420 # DEBUG
421 # if (!defined $contents) {
422 # use Carp;
423 # confess "output_highlight got called with no args?\n";
426 if ($output_mode eq "html" || $output_mode eq "xml") {
427 $contents = local_unescape($contents);
428 # convert data read & converted thru xml_escape() into &xyz; format:
429 $contents =~ s/\\\\\\/&/g;
431 # print STDERR "contents b4:$contents\n";
432 eval $dohighlight;
433 die $@ if $@;
434 # print STDERR "contents af:$contents\n";
436 foreach $line (split "\n", $contents) {
437 if ($line eq ""){
438 print $lineprefix, local_unescape($blankline);
439 } else {
440 $line =~ s/\\\\\\/\&/g;
441 if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
442 print "\\&$line";
443 } else {
444 print $lineprefix, $line;
447 print "\n";
451 #output sections in html
452 sub output_section_html(%) {
453 my %args = %{$_[0]};
454 my $section;
456 foreach $section (@{$args{'sectionlist'}}) {
457 print "<h3>$section</h3>\n";
458 print "<blockquote>\n";
459 output_highlight($args{'sections'}{$section});
460 print "</blockquote>\n";
464 # output enum in html
465 sub output_enum_html(%) {
466 my %args = %{$_[0]};
467 my ($parameter);
468 my $count;
469 print "<h2>enum ".$args{'enum'}."</h2>\n";
471 print "<b>enum ".$args{'enum'}."</b> {<br>\n";
472 $count = 0;
473 foreach $parameter (@{$args{'parameterlist'}}) {
474 print " <b>".$parameter."</b>";
475 if ($count != $#{$args{'parameterlist'}}) {
476 $count++;
477 print ",\n";
479 print "<br>";
481 print "};<br>\n";
483 print "<h3>Constants</h3>\n";
484 print "<dl>\n";
485 foreach $parameter (@{$args{'parameterlist'}}) {
486 print "<dt><b>".$parameter."</b>\n";
487 print "<dd>";
488 output_highlight($args{'parameterdescs'}{$parameter});
490 print "</dl>\n";
491 output_section_html(@_);
492 print "<hr>\n";
495 # output typedef in html
496 sub output_typedef_html(%) {
497 my %args = %{$_[0]};
498 my ($parameter);
499 my $count;
500 print "<h2>typedef ".$args{'typedef'}."</h2>\n";
502 print "<b>typedef ".$args{'typedef'}."</b>\n";
503 output_section_html(@_);
504 print "<hr>\n";
507 # output struct in html
508 sub output_struct_html(%) {
509 my %args = %{$_[0]};
510 my ($parameter);
512 print "<h2>".$args{'type'}." ".$args{'struct'}. " - " .$args{'purpose'}."</h2>\n";
513 print "<b>".$args{'type'}." ".$args{'struct'}."</b> {<br>\n";
514 foreach $parameter (@{$args{'parameterlist'}}) {
515 if ($parameter =~ /^#/) {
516 print "$parameter<br>\n";
517 next;
519 my $parameter_name = $parameter;
520 $parameter_name =~ s/\[.*//;
522 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
523 $type = $args{'parametertypes'}{$parameter};
524 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
525 # pointer-to-function
526 print "&nbsp; &nbsp; <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
527 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
528 # bitfield
529 print "&nbsp; &nbsp; <i>$1</i> <b>$parameter</b>$2;<br>\n";
530 } else {
531 print "&nbsp; &nbsp; <i>$type</i> <b>$parameter</b>;<br>\n";
534 print "};<br>\n";
536 print "<h3>Members</h3>\n";
537 print "<dl>\n";
538 foreach $parameter (@{$args{'parameterlist'}}) {
539 ($parameter =~ /^#/) && next;
541 my $parameter_name = $parameter;
542 $parameter_name =~ s/\[.*//;
544 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
545 print "<dt><b>".$parameter."</b>\n";
546 print "<dd>";
547 output_highlight($args{'parameterdescs'}{$parameter_name});
549 print "</dl>\n";
550 output_section_html(@_);
551 print "<hr>\n";
554 # output function in html
555 sub output_function_html(%) {
556 my %args = %{$_[0]};
557 my ($parameter, $section);
558 my $count;
560 print "<h2>" .$args{'function'}." - ".$args{'purpose'}."</h2>\n";
561 print "<i>".$args{'functiontype'}."</i>\n";
562 print "<b>".$args{'function'}."</b>\n";
563 print "(";
564 $count = 0;
565 foreach $parameter (@{$args{'parameterlist'}}) {
566 $type = $args{'parametertypes'}{$parameter};
567 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
568 # pointer-to-function
569 print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
570 } else {
571 print "<i>".$type."</i> <b>".$parameter."</b>";
573 if ($count != $#{$args{'parameterlist'}}) {
574 $count++;
575 print ",\n";
578 print ")\n";
580 print "<h3>Arguments</h3>\n";
581 print "<dl>\n";
582 foreach $parameter (@{$args{'parameterlist'}}) {
583 my $parameter_name = $parameter;
584 $parameter_name =~ s/\[.*//;
586 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
587 print "<dt><b>".$parameter."</b>\n";
588 print "<dd>";
589 output_highlight($args{'parameterdescs'}{$parameter_name});
591 print "</dl>\n";
592 output_section_html(@_);
593 print "<hr>\n";
596 # output DOC: block header in html
597 sub output_blockhead_html(%) {
598 my %args = %{$_[0]};
599 my ($parameter, $section);
600 my $count;
602 foreach $section (@{$args{'sectionlist'}}) {
603 print "<h3>$section</h3>\n";
604 print "<ul>\n";
605 output_highlight($args{'sections'}{$section});
606 print "</ul>\n";
608 print "<hr>\n";
611 sub output_section_xml(%) {
612 my %args = %{$_[0]};
613 my $section;
614 # print out each section
615 $lineprefix=" ";
616 foreach $section (@{$args{'sectionlist'}}) {
617 print "<refsect1>\n";
618 print "<title>$section</title>\n";
619 if ($section =~ m/EXAMPLE/i) {
620 print "<informalexample><programlisting>\n";
621 } else {
622 print "<para>\n";
624 output_highlight($args{'sections'}{$section});
625 if ($section =~ m/EXAMPLE/i) {
626 print "</programlisting></informalexample>\n";
627 } else {
628 print "</para>\n";
630 print "</refsect1>\n";
634 # output function in XML DocBook
635 sub output_function_xml(%) {
636 my %args = %{$_[0]};
637 my ($parameter, $section);
638 my $count;
639 my $id;
641 $id = "API-".$args{'function'};
642 $id =~ s/[^A-Za-z0-9]/-/g;
644 print "<refentry id=\"$id\">\n";
645 print "<refentryinfo>\n";
646 print " <title>LINUX</title>\n";
647 print " <productname>Kernel Hackers Manual</productname>\n";
648 print " <date>$man_date</date>\n";
649 print "</refentryinfo>\n";
650 print "<refmeta>\n";
651 print " <refentrytitle><phrase>".$args{'function'}."</phrase></refentrytitle>\n";
652 print " <manvolnum>9</manvolnum>\n";
653 print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
654 print "</refmeta>\n";
655 print "<refnamediv>\n";
656 print " <refname>".$args{'function'}."</refname>\n";
657 print " <refpurpose>\n";
658 print " ";
659 output_highlight ($args{'purpose'});
660 print " </refpurpose>\n";
661 print "</refnamediv>\n";
663 print "<refsynopsisdiv>\n";
664 print " <title>Synopsis</title>\n";
665 print " <funcsynopsis><funcprototype>\n";
666 print " <funcdef>".$args{'functiontype'}." ";
667 print "<function>".$args{'function'}." </function></funcdef>\n";
669 $count = 0;
670 if ($#{$args{'parameterlist'}} >= 0) {
671 foreach $parameter (@{$args{'parameterlist'}}) {
672 $type = $args{'parametertypes'}{$parameter};
673 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
674 # pointer-to-function
675 print " <paramdef>$1<parameter>$parameter</parameter>)\n";
676 print " <funcparams>$2</funcparams></paramdef>\n";
677 } else {
678 print " <paramdef>".$type;
679 print " <parameter>$parameter</parameter></paramdef>\n";
682 } else {
683 print " <void/>\n";
685 print " </funcprototype></funcsynopsis>\n";
686 print "</refsynopsisdiv>\n";
688 # print parameters
689 print "<refsect1>\n <title>Arguments</title>\n";
690 if ($#{$args{'parameterlist'}} >= 0) {
691 print " <variablelist>\n";
692 foreach $parameter (@{$args{'parameterlist'}}) {
693 my $parameter_name = $parameter;
694 $parameter_name =~ s/\[.*//;
696 print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n";
697 print " <listitem>\n <para>\n";
698 $lineprefix=" ";
699 output_highlight($args{'parameterdescs'}{$parameter_name});
700 print " </para>\n </listitem>\n </varlistentry>\n";
702 print " </variablelist>\n";
703 } else {
704 print " <para>\n None\n </para>\n";
706 print "</refsect1>\n";
708 output_section_xml(@_);
709 print "</refentry>\n\n";
712 # output struct in XML DocBook
713 sub output_struct_xml(%) {
714 my %args = %{$_[0]};
715 my ($parameter, $section);
716 my $id;
718 $id = "API-struct-".$args{'struct'};
719 $id =~ s/[^A-Za-z0-9]/-/g;
721 print "<refentry id=\"$id\">\n";
722 print "<refentryinfo>\n";
723 print " <title>LINUX</title>\n";
724 print " <productname>Kernel Hackers Manual</productname>\n";
725 print " <date>$man_date</date>\n";
726 print "</refentryinfo>\n";
727 print "<refmeta>\n";
728 print " <refentrytitle><phrase>".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>\n";
729 print " <manvolnum>9</manvolnum>\n";
730 print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
731 print "</refmeta>\n";
732 print "<refnamediv>\n";
733 print " <refname>".$args{'type'}." ".$args{'struct'}."</refname>\n";
734 print " <refpurpose>\n";
735 print " ";
736 output_highlight ($args{'purpose'});
737 print " </refpurpose>\n";
738 print "</refnamediv>\n";
740 print "<refsynopsisdiv>\n";
741 print " <title>Synopsis</title>\n";
742 print " <programlisting>\n";
743 print $args{'type'}." ".$args{'struct'}." {\n";
744 foreach $parameter (@{$args{'parameterlist'}}) {
745 if ($parameter =~ /^#/) {
746 print "$parameter\n";
747 next;
750 my $parameter_name = $parameter;
751 $parameter_name =~ s/\[.*//;
753 defined($args{'parameterdescs'}{$parameter_name}) || next;
754 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
755 $type = $args{'parametertypes'}{$parameter};
756 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
757 # pointer-to-function
758 print " $1 $parameter) ($2);\n";
759 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
760 # bitfield
761 print " $1 $parameter$2;\n";
762 } else {
763 print " ".$type." ".$parameter.";\n";
766 print "};";
767 print " </programlisting>\n";
768 print "</refsynopsisdiv>\n";
770 print " <refsect1>\n";
771 print " <title>Members</title>\n";
773 print " <variablelist>\n";
774 foreach $parameter (@{$args{'parameterlist'}}) {
775 ($parameter =~ /^#/) && next;
777 my $parameter_name = $parameter;
778 $parameter_name =~ s/\[.*//;
780 defined($args{'parameterdescs'}{$parameter_name}) || next;
781 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
782 print " <varlistentry>";
783 print " <term>$parameter</term>\n";
784 print " <listitem><para>\n";
785 output_highlight($args{'parameterdescs'}{$parameter_name});
786 print " </para></listitem>\n";
787 print " </varlistentry>\n";
789 print " </variablelist>\n";
790 print " </refsect1>\n";
792 output_section_xml(@_);
794 print "</refentry>\n\n";
797 # output enum in XML DocBook
798 sub output_enum_xml(%) {
799 my %args = %{$_[0]};
800 my ($parameter, $section);
801 my $count;
802 my $id;
804 $id = "API-enum-".$args{'enum'};
805 $id =~ s/[^A-Za-z0-9]/-/g;
807 print "<refentry id=\"$id\">\n";
808 print "<refentryinfo>\n";
809 print " <title>LINUX</title>\n";
810 print " <productname>Kernel Hackers Manual</productname>\n";
811 print " <date>$man_date</date>\n";
812 print "</refentryinfo>\n";
813 print "<refmeta>\n";
814 print " <refentrytitle><phrase>enum ".$args{'enum'}."</phrase></refentrytitle>\n";
815 print " <manvolnum>9</manvolnum>\n";
816 print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
817 print "</refmeta>\n";
818 print "<refnamediv>\n";
819 print " <refname>enum ".$args{'enum'}."</refname>\n";
820 print " <refpurpose>\n";
821 print " ";
822 output_highlight ($args{'purpose'});
823 print " </refpurpose>\n";
824 print "</refnamediv>\n";
826 print "<refsynopsisdiv>\n";
827 print " <title>Synopsis</title>\n";
828 print " <programlisting>\n";
829 print "enum ".$args{'enum'}." {\n";
830 $count = 0;
831 foreach $parameter (@{$args{'parameterlist'}}) {
832 print " $parameter";
833 if ($count != $#{$args{'parameterlist'}}) {
834 $count++;
835 print ",";
837 print "\n";
839 print "};";
840 print " </programlisting>\n";
841 print "</refsynopsisdiv>\n";
843 print "<refsect1>\n";
844 print " <title>Constants</title>\n";
845 print " <variablelist>\n";
846 foreach $parameter (@{$args{'parameterlist'}}) {
847 my $parameter_name = $parameter;
848 $parameter_name =~ s/\[.*//;
850 print " <varlistentry>";
851 print " <term>$parameter</term>\n";
852 print " <listitem><para>\n";
853 output_highlight($args{'parameterdescs'}{$parameter_name});
854 print " </para></listitem>\n";
855 print " </varlistentry>\n";
857 print " </variablelist>\n";
858 print "</refsect1>\n";
860 output_section_xml(@_);
862 print "</refentry>\n\n";
865 # output typedef in XML DocBook
866 sub output_typedef_xml(%) {
867 my %args = %{$_[0]};
868 my ($parameter, $section);
869 my $id;
871 $id = "API-typedef-".$args{'typedef'};
872 $id =~ s/[^A-Za-z0-9]/-/g;
874 print "<refentry id=\"$id\">\n";
875 print "<refentryinfo>\n";
876 print " <title>LINUX</title>\n";
877 print " <productname>Kernel Hackers Manual</productname>\n";
878 print " <date>$man_date</date>\n";
879 print "</refentryinfo>\n";
880 print "<refmeta>\n";
881 print " <refentrytitle><phrase>typedef ".$args{'typedef'}."</phrase></refentrytitle>\n";
882 print " <manvolnum>9</manvolnum>\n";
883 print "</refmeta>\n";
884 print "<refnamediv>\n";
885 print " <refname>typedef ".$args{'typedef'}."</refname>\n";
886 print " <refpurpose>\n";
887 print " ";
888 output_highlight ($args{'purpose'});
889 print " </refpurpose>\n";
890 print "</refnamediv>\n";
892 print "<refsynopsisdiv>\n";
893 print " <title>Synopsis</title>\n";
894 print " <synopsis>typedef ".$args{'typedef'}.";</synopsis>\n";
895 print "</refsynopsisdiv>\n";
897 output_section_xml(@_);
899 print "</refentry>\n\n";
902 # output in XML DocBook
903 sub output_blockhead_xml(%) {
904 my %args = %{$_[0]};
905 my ($parameter, $section);
906 my $count;
908 my $id = $args{'module'};
909 $id =~ s/[^A-Za-z0-9]/-/g;
911 # print out each section
912 $lineprefix=" ";
913 foreach $section (@{$args{'sectionlist'}}) {
914 if (!$args{'content-only'}) {
915 print "<refsect1>\n <title>$section</title>\n";
917 if ($section =~ m/EXAMPLE/i) {
918 print "<example><para>\n";
919 } else {
920 print "<para>\n";
922 output_highlight($args{'sections'}{$section});
923 if ($section =~ m/EXAMPLE/i) {
924 print "</para></example>\n";
925 } else {
926 print "</para>";
928 if (!$args{'content-only'}) {
929 print "\n</refsect1>\n";
933 print "\n\n";
936 # output in XML DocBook
937 sub output_function_gnome {
938 my %args = %{$_[0]};
939 my ($parameter, $section);
940 my $count;
941 my $id;
943 $id = $args{'module'}."-".$args{'function'};
944 $id =~ s/[^A-Za-z0-9]/-/g;
946 print "<sect2>\n";
947 print " <title id=\"$id\">".$args{'function'}."</title>\n";
949 print " <funcsynopsis>\n";
950 print " <funcdef>".$args{'functiontype'}." ";
951 print "<function>".$args{'function'}." ";
952 print "</function></funcdef>\n";
954 $count = 0;
955 if ($#{$args{'parameterlist'}} >= 0) {
956 foreach $parameter (@{$args{'parameterlist'}}) {
957 $type = $args{'parametertypes'}{$parameter};
958 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
959 # pointer-to-function
960 print " <paramdef>$1 <parameter>$parameter</parameter>)\n";
961 print " <funcparams>$2</funcparams></paramdef>\n";
962 } else {
963 print " <paramdef>".$type;
964 print " <parameter>$parameter</parameter></paramdef>\n";
967 } else {
968 print " <void>\n";
970 print " </funcsynopsis>\n";
971 if ($#{$args{'parameterlist'}} >= 0) {
972 print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
973 print "<tgroup cols=\"2\">\n";
974 print "<colspec colwidth=\"2*\">\n";
975 print "<colspec colwidth=\"8*\">\n";
976 print "<tbody>\n";
977 foreach $parameter (@{$args{'parameterlist'}}) {
978 my $parameter_name = $parameter;
979 $parameter_name =~ s/\[.*//;
981 print " <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
982 print " <entry>\n";
983 $lineprefix=" ";
984 output_highlight($args{'parameterdescs'}{$parameter_name});
985 print " </entry></row>\n";
987 print " </tbody></tgroup></informaltable>\n";
988 } else {
989 print " <para>\n None\n </para>\n";
992 # print out each section
993 $lineprefix=" ";
994 foreach $section (@{$args{'sectionlist'}}) {
995 print "<simplesect>\n <title>$section</title>\n";
996 if ($section =~ m/EXAMPLE/i) {
997 print "<example><programlisting>\n";
998 } else {
1000 print "<para>\n";
1001 output_highlight($args{'sections'}{$section});
1002 print "</para>\n";
1003 if ($section =~ m/EXAMPLE/i) {
1004 print "</programlisting></example>\n";
1005 } else {
1007 print " </simplesect>\n";
1010 print "</sect2>\n\n";
1014 # output function in man
1015 sub output_function_man(%) {
1016 my %args = %{$_[0]};
1017 my ($parameter, $section);
1018 my $count;
1020 print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
1022 print ".SH NAME\n";
1023 print $args{'function'}." \\- ".$args{'purpose'}."\n";
1025 print ".SH SYNOPSIS\n";
1026 if ($args{'functiontype'} ne "") {
1027 print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n";
1028 } else {
1029 print ".B \"".$args{'function'}."\n";
1031 $count = 0;
1032 my $parenth = "(";
1033 my $post = ",";
1034 foreach my $parameter (@{$args{'parameterlist'}}) {
1035 if ($count == $#{$args{'parameterlist'}}) {
1036 $post = ");";
1038 $type = $args{'parametertypes'}{$parameter};
1039 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1040 # pointer-to-function
1041 print ".BI \"".$parenth.$1."\" ".$parameter." \") (".$2.")".$post."\"\n";
1042 } else {
1043 $type =~ s/([^\*])$/$1 /;
1044 print ".BI \"".$parenth.$type."\" ".$parameter." \"".$post."\"\n";
1046 $count++;
1047 $parenth = "";
1050 print ".SH ARGUMENTS\n";
1051 foreach $parameter (@{$args{'parameterlist'}}) {
1052 my $parameter_name = $parameter;
1053 $parameter_name =~ s/\[.*//;
1055 print ".IP \"".$parameter."\" 12\n";
1056 output_highlight($args{'parameterdescs'}{$parameter_name});
1058 foreach $section (@{$args{'sectionlist'}}) {
1059 print ".SH \"", uc $section, "\"\n";
1060 output_highlight($args{'sections'}{$section});
1065 # output enum in man
1066 sub output_enum_man(%) {
1067 my %args = %{$_[0]};
1068 my ($parameter, $section);
1069 my $count;
1071 print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
1073 print ".SH NAME\n";
1074 print "enum ".$args{'enum'}." \\- ".$args{'purpose'}."\n";
1076 print ".SH SYNOPSIS\n";
1077 print "enum ".$args{'enum'}." {\n";
1078 $count = 0;
1079 foreach my $parameter (@{$args{'parameterlist'}}) {
1080 print ".br\n.BI \" $parameter\"\n";
1081 if ($count == $#{$args{'parameterlist'}}) {
1082 print "\n};\n";
1083 last;
1085 else {
1086 print ", \n.br\n";
1088 $count++;
1091 print ".SH Constants\n";
1092 foreach $parameter (@{$args{'parameterlist'}}) {
1093 my $parameter_name = $parameter;
1094 $parameter_name =~ s/\[.*//;
1096 print ".IP \"".$parameter."\" 12\n";
1097 output_highlight($args{'parameterdescs'}{$parameter_name});
1099 foreach $section (@{$args{'sectionlist'}}) {
1100 print ".SH \"$section\"\n";
1101 output_highlight($args{'sections'}{$section});
1106 # output struct in man
1107 sub output_struct_man(%) {
1108 my %args = %{$_[0]};
1109 my ($parameter, $section);
1111 print ".TH \"$args{'module'}\" 9 \"".$args{'type'}." ".$args{'struct'}."\" \"$man_date\" \"API Manual\" LINUX\n";
1113 print ".SH NAME\n";
1114 print $args{'type'}." ".$args{'struct'}." \\- ".$args{'purpose'}."\n";
1116 print ".SH SYNOPSIS\n";
1117 print $args{'type'}." ".$args{'struct'}." {\n.br\n";
1119 foreach my $parameter (@{$args{'parameterlist'}}) {
1120 if ($parameter =~ /^#/) {
1121 print ".BI \"$parameter\"\n.br\n";
1122 next;
1124 my $parameter_name = $parameter;
1125 $parameter_name =~ s/\[.*//;
1127 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1128 $type = $args{'parametertypes'}{$parameter};
1129 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1130 # pointer-to-function
1131 print ".BI \" ".$1."\" ".$parameter." \") (".$2.")"."\"\n;\n";
1132 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1133 # bitfield
1134 print ".BI \" ".$1."\ \" ".$parameter.$2." \""."\"\n;\n";
1135 } else {
1136 $type =~ s/([^\*])$/$1 /;
1137 print ".BI \" ".$type."\" ".$parameter." \""."\"\n;\n";
1139 print "\n.br\n";
1141 print "};\n.br\n";
1143 print ".SH Members\n";
1144 foreach $parameter (@{$args{'parameterlist'}}) {
1145 ($parameter =~ /^#/) && next;
1147 my $parameter_name = $parameter;
1148 $parameter_name =~ s/\[.*//;
1150 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1151 print ".IP \"".$parameter."\" 12\n";
1152 output_highlight($args{'parameterdescs'}{$parameter_name});
1154 foreach $section (@{$args{'sectionlist'}}) {
1155 print ".SH \"$section\"\n";
1156 output_highlight($args{'sections'}{$section});
1161 # output typedef in man
1162 sub output_typedef_man(%) {
1163 my %args = %{$_[0]};
1164 my ($parameter, $section);
1166 print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
1168 print ".SH NAME\n";
1169 print "typedef ".$args{'typedef'}." \\- ".$args{'purpose'}."\n";
1171 foreach $section (@{$args{'sectionlist'}}) {
1172 print ".SH \"$section\"\n";
1173 output_highlight($args{'sections'}{$section});
1177 sub output_blockhead_man(%) {
1178 my %args = %{$_[0]};
1179 my ($parameter, $section);
1180 my $count;
1182 print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
1184 foreach $section (@{$args{'sectionlist'}}) {
1185 print ".SH \"$section\"\n";
1186 output_highlight($args{'sections'}{$section});
1191 # output in text
1192 sub output_function_text(%) {
1193 my %args = %{$_[0]};
1194 my ($parameter, $section);
1195 my $start;
1197 print "Name:\n\n";
1198 print $args{'function'}." - ".$args{'purpose'}."\n";
1200 print "\nSynopsis:\n\n";
1201 if ($args{'functiontype'} ne "") {
1202 $start = $args{'functiontype'}." ".$args{'function'}." (";
1203 } else {
1204 $start = $args{'function'}." (";
1206 print $start;
1208 my $count = 0;
1209 foreach my $parameter (@{$args{'parameterlist'}}) {
1210 $type = $args{'parametertypes'}{$parameter};
1211 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1212 # pointer-to-function
1213 print $1.$parameter.") (".$2;
1214 } else {
1215 print $type." ".$parameter;
1217 if ($count != $#{$args{'parameterlist'}}) {
1218 $count++;
1219 print ",\n";
1220 print " " x length($start);
1221 } else {
1222 print ");\n\n";
1226 print "Arguments:\n\n";
1227 foreach $parameter (@{$args{'parameterlist'}}) {
1228 my $parameter_name = $parameter;
1229 $parameter_name =~ s/\[.*//;
1231 print $parameter."\n\t".$args{'parameterdescs'}{$parameter_name}."\n";
1233 output_section_text(@_);
1236 #output sections in text
1237 sub output_section_text(%) {
1238 my %args = %{$_[0]};
1239 my $section;
1241 print "\n";
1242 foreach $section (@{$args{'sectionlist'}}) {
1243 print "$section:\n\n";
1244 output_highlight($args{'sections'}{$section});
1246 print "\n\n";
1249 # output enum in text
1250 sub output_enum_text(%) {
1251 my %args = %{$_[0]};
1252 my ($parameter);
1253 my $count;
1254 print "Enum:\n\n";
1256 print "enum ".$args{'enum'}." - ".$args{'purpose'}."\n\n";
1257 print "enum ".$args{'enum'}." {\n";
1258 $count = 0;
1259 foreach $parameter (@{$args{'parameterlist'}}) {
1260 print "\t$parameter";
1261 if ($count != $#{$args{'parameterlist'}}) {
1262 $count++;
1263 print ",";
1265 print "\n";
1267 print "};\n\n";
1269 print "Constants:\n\n";
1270 foreach $parameter (@{$args{'parameterlist'}}) {
1271 print "$parameter\n\t";
1272 print $args{'parameterdescs'}{$parameter}."\n";
1275 output_section_text(@_);
1278 # output typedef in text
1279 sub output_typedef_text(%) {
1280 my %args = %{$_[0]};
1281 my ($parameter);
1282 my $count;
1283 print "Typedef:\n\n";
1285 print "typedef ".$args{'typedef'}." - ".$args{'purpose'}."\n";
1286 output_section_text(@_);
1289 # output struct as text
1290 sub output_struct_text(%) {
1291 my %args = %{$_[0]};
1292 my ($parameter);
1294 print $args{'type'}." ".$args{'struct'}." - ".$args{'purpose'}."\n\n";
1295 print $args{'type'}." ".$args{'struct'}." {\n";
1296 foreach $parameter (@{$args{'parameterlist'}}) {
1297 if ($parameter =~ /^#/) {
1298 print "$parameter\n";
1299 next;
1302 my $parameter_name = $parameter;
1303 $parameter_name =~ s/\[.*//;
1305 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1306 $type = $args{'parametertypes'}{$parameter};
1307 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1308 # pointer-to-function
1309 print "\t$1 $parameter) ($2);\n";
1310 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1311 # bitfield
1312 print "\t$1 $parameter$2;\n";
1313 } else {
1314 print "\t".$type." ".$parameter.";\n";
1317 print "};\n\n";
1319 print "Members:\n\n";
1320 foreach $parameter (@{$args{'parameterlist'}}) {
1321 ($parameter =~ /^#/) && next;
1323 my $parameter_name = $parameter;
1324 $parameter_name =~ s/\[.*//;
1326 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1327 print "$parameter\n\t";
1328 print $args{'parameterdescs'}{$parameter_name}."\n";
1330 print "\n";
1331 output_section_text(@_);
1334 sub output_blockhead_text(%) {
1335 my %args = %{$_[0]};
1336 my ($parameter, $section);
1338 foreach $section (@{$args{'sectionlist'}}) {
1339 print " $section:\n";
1340 print " -> ";
1341 output_highlight($args{'sections'}{$section});
1346 # generic output function for all types (function, struct/union, typedef, enum);
1347 # calls the generated, variable output_ function name based on
1348 # functype and output_mode
1349 sub output_declaration {
1350 no strict 'refs';
1351 my $name = shift;
1352 my $functype = shift;
1353 my $func = "output_${functype}_$output_mode";
1354 if (($function_only==0) ||
1355 ( $function_only == 1 && defined($function_table{$name})) ||
1356 ( $function_only == 2 && !defined($function_table{$name})))
1358 &$func(@_);
1359 $section_counter++;
1364 # generic output function - calls the right one based on current output mode.
1365 sub output_blockhead {
1366 no strict 'refs';
1367 my $func = "output_blockhead_".$output_mode;
1368 &$func(@_);
1369 $section_counter++;
1373 # takes a declaration (struct, union, enum, typedef) and
1374 # invokes the right handler. NOT called for functions.
1375 sub dump_declaration($$) {
1376 no strict 'refs';
1377 my ($prototype, $file) = @_;
1378 my $func = "dump_".$decl_type;
1379 &$func(@_);
1382 sub dump_union($$) {
1383 dump_struct(@_);
1386 sub dump_struct($$) {
1387 my $x = shift;
1388 my $file = shift;
1390 if ($x =~/(struct|union)\s+(\w+)\s*{(.*)}/) {
1391 $declaration_name = $2;
1392 my $members = $3;
1394 # ignore embedded structs or unions
1395 $members =~ s/{.*?}//g;
1397 # ignore members marked private:
1398 $members =~ s/\/\*.*?private:.*?public:.*?\*\///gos;
1399 $members =~ s/\/\*.*?private:.*//gos;
1400 # strip comments:
1401 $members =~ s/\/\*.*?\*\///gos;
1403 create_parameterlist($members, ';', $file);
1405 output_declaration($declaration_name,
1406 'struct',
1407 {'struct' => $declaration_name,
1408 'module' => $modulename,
1409 'parameterlist' => \@parameterlist,
1410 'parameterdescs' => \%parameterdescs,
1411 'parametertypes' => \%parametertypes,
1412 'sectionlist' => \@sectionlist,
1413 'sections' => \%sections,
1414 'purpose' => $declaration_purpose,
1415 'type' => $decl_type
1418 else {
1419 print STDERR "Error(${file}:$.): Cannot parse struct or union!\n";
1420 ++$errors;
1424 sub dump_enum($$) {
1425 my $x = shift;
1426 my $file = shift;
1428 $x =~ s@/\*.*?\*/@@gos; # strip comments.
1429 if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
1430 $declaration_name = $1;
1431 my $members = $2;
1433 foreach my $arg (split ',', $members) {
1434 $arg =~ s/^\s*(\w+).*/$1/;
1435 push @parameterlist, $arg;
1436 if (!$parameterdescs{$arg}) {
1437 $parameterdescs{$arg} = $undescribed;
1438 print STDERR "Warning(${file}:$.): Enum value '$arg' ".
1439 "not described in enum '$declaration_name'\n";
1444 output_declaration($declaration_name,
1445 'enum',
1446 {'enum' => $declaration_name,
1447 'module' => $modulename,
1448 'parameterlist' => \@parameterlist,
1449 'parameterdescs' => \%parameterdescs,
1450 'sectionlist' => \@sectionlist,
1451 'sections' => \%sections,
1452 'purpose' => $declaration_purpose
1455 else {
1456 print STDERR "Error(${file}:$.): Cannot parse enum!\n";
1457 ++$errors;
1461 sub dump_typedef($$) {
1462 my $x = shift;
1463 my $file = shift;
1465 $x =~ s@/\*.*?\*/@@gos; # strip comments.
1466 while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
1467 $x =~ s/\(*.\)\s*;$/;/;
1468 $x =~ s/\[*.\]\s*;$/;/;
1471 if ($x =~ /typedef.*\s+(\w+)\s*;/) {
1472 $declaration_name = $1;
1474 output_declaration($declaration_name,
1475 'typedef',
1476 {'typedef' => $declaration_name,
1477 'module' => $modulename,
1478 'sectionlist' => \@sectionlist,
1479 'sections' => \%sections,
1480 'purpose' => $declaration_purpose
1483 else {
1484 print STDERR "Error(${file}:$.): Cannot parse typedef!\n";
1485 ++$errors;
1489 sub create_parameterlist($$$) {
1490 my $args = shift;
1491 my $splitter = shift;
1492 my $file = shift;
1493 my $type;
1494 my $param;
1496 # temporarily replace commas inside function pointer definition
1497 while ($args =~ /(\([^\),]+),/) {
1498 $args =~ s/(\([^\),]+),/$1#/g;
1501 foreach my $arg (split($splitter, $args)) {
1502 # strip comments
1503 $arg =~ s/\/\*.*\*\///;
1504 # strip leading/trailing spaces
1505 $arg =~ s/^\s*//;
1506 $arg =~ s/\s*$//;
1507 $arg =~ s/\s+/ /;
1509 if ($arg =~ /^#/) {
1510 # Treat preprocessor directive as a typeless variable just to fill
1511 # corresponding data structures "correctly". Catch it later in
1512 # output_* subs.
1513 push_parameter($arg, "", $file);
1514 } elsif ($arg =~ m/\(.*\*/) {
1515 # pointer-to-function
1516 $arg =~ tr/#/,/;
1517 $arg =~ m/[^\(]+\(\*\s*([^\)]+)\)/;
1518 $param = $1;
1519 $type = $arg;
1520 $type =~ s/([^\(]+\(\*)$param/$1/;
1521 push_parameter($param, $type, $file);
1522 } elsif ($arg) {
1523 $arg =~ s/\s*:\s*/:/g;
1524 $arg =~ s/\s*\[/\[/g;
1526 my @args = split('\s*,\s*', $arg);
1527 if ($args[0] =~ m/\*/) {
1528 $args[0] =~ s/(\*+)\s*/ $1/;
1531 my @first_arg;
1532 if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
1533 shift @args;
1534 push(@first_arg, split('\s+', $1));
1535 push(@first_arg, $2);
1536 } else {
1537 @first_arg = split('\s+', shift @args);
1540 unshift(@args, pop @first_arg);
1541 $type = join " ", @first_arg;
1543 foreach $param (@args) {
1544 if ($param =~ m/^(\*+)\s*(.*)/) {
1545 push_parameter($2, "$type $1", $file);
1547 elsif ($param =~ m/(.*?):(\d+)/) {
1548 push_parameter($1, "$type:$2", $file)
1550 else {
1551 push_parameter($param, $type, $file);
1558 sub push_parameter($$$) {
1559 my $param = shift;
1560 my $type = shift;
1561 my $file = shift;
1563 if (($anon_struct_union == 1) && ($type eq "") &&
1564 ($param eq "}")) {
1565 return; # ignore the ending }; from anon. struct/union
1568 $anon_struct_union = 0;
1569 my $param_name = $param;
1570 $param_name =~ s/\[.*//;
1572 if ($type eq "" && $param =~ /\.\.\.$/)
1574 $type="";
1575 $parameterdescs{$param} = "variable arguments";
1577 elsif ($type eq "" && ($param eq "" or $param eq "void"))
1579 $type="";
1580 $param="void";
1581 $parameterdescs{void} = "no arguments";
1583 elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
1584 # handle unnamed (anonymous) union or struct:
1586 $type = $param;
1587 $param = "{unnamed_" . $param . "}";
1588 $parameterdescs{$param} = "anonymous\n";
1589 $anon_struct_union = 1;
1592 # warn if parameter has no description
1593 # (but ignore ones starting with # as these are not parameters
1594 # but inline preprocessor statements);
1595 # also ignore unnamed structs/unions;
1596 if (!$anon_struct_union) {
1597 if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {
1599 $parameterdescs{$param_name} = $undescribed;
1601 if (($type eq 'function') || ($type eq 'enum')) {
1602 print STDERR "Warning(${file}:$.): Function parameter ".
1603 "or member '$param' not " .
1604 "described in '$declaration_name'\n";
1606 print STDERR "Warning(${file}:$.):".
1607 " No description found for parameter '$param'\n";
1608 ++$warnings;
1612 push @parameterlist, $param;
1613 $parametertypes{$param} = $type;
1617 # takes a function prototype and the name of the current file being
1618 # processed and spits out all the details stored in the global
1619 # arrays/hashes.
1620 sub dump_function($$) {
1621 my $prototype = shift;
1622 my $file = shift;
1624 $prototype =~ s/^static +//;
1625 $prototype =~ s/^extern +//;
1626 $prototype =~ s/^fastcall +//;
1627 $prototype =~ s/^asmlinkage +//;
1628 $prototype =~ s/^inline +//;
1629 $prototype =~ s/^__inline__ +//;
1630 $prototype =~ s/^__inline +//;
1631 $prototype =~ s/^__always_inline +//;
1632 $prototype =~ s/^noinline +//;
1633 $prototype =~ s/__devinit +//;
1634 $prototype =~ s/^#define\s+//; #ak added
1635 $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
1637 # Yes, this truly is vile. We are looking for:
1638 # 1. Return type (may be nothing if we're looking at a macro)
1639 # 2. Function name
1640 # 3. Function parameters.
1642 # All the while we have to watch out for function pointer parameters
1643 # (which IIRC is what the two sections are for), C types (these
1644 # regexps don't even start to express all the possibilities), and
1645 # so on.
1647 # If you mess with these regexps, it's a good idea to check that
1648 # the following functions' documentation still comes out right:
1649 # - parport_register_device (function pointer parameters)
1650 # - atomic_set (macro)
1651 # - pci_match_device, __copy_to_user (long return type)
1653 if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1654 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1655 $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1656 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1657 $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1658 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1659 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1660 $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1661 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1662 $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1663 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1664 $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1665 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1666 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1667 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1668 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1669 $prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) {
1670 $return_type = $1;
1671 $declaration_name = $2;
1672 my $args = $3;
1674 create_parameterlist($args, ',', $file);
1675 } else {
1676 print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n";
1677 ++$errors;
1678 return;
1681 output_declaration($declaration_name,
1682 'function',
1683 {'function' => $declaration_name,
1684 'module' => $modulename,
1685 'functiontype' => $return_type,
1686 'parameterlist' => \@parameterlist,
1687 'parameterdescs' => \%parameterdescs,
1688 'parametertypes' => \%parametertypes,
1689 'sectionlist' => \@sectionlist,
1690 'sections' => \%sections,
1691 'purpose' => $declaration_purpose
1695 sub process_file($);
1697 # Read the file that maps relative names to absolute names for
1698 # separate source and object directories and for shadow trees.
1699 if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
1700 my ($relname, $absname);
1701 while(<SOURCE_MAP>) {
1702 chop();
1703 ($relname, $absname) = (split())[0..1];
1704 $relname =~ s:^/+::;
1705 $source_map{$relname} = $absname;
1707 close(SOURCE_MAP);
1710 if ($filelist) {
1711 open(FLIST,"<$filelist") or die "Can't open file list $filelist";
1712 while(<FLIST>) {
1713 chop;
1714 process_file($_);
1718 foreach (@ARGV) {
1719 chomp;
1720 process_file($_);
1722 if ($verbose && $errors) {
1723 print STDERR "$errors errors\n";
1725 if ($verbose && $warnings) {
1726 print STDERR "$warnings warnings\n";
1729 exit($errors);
1731 sub reset_state {
1732 $function = "";
1733 %constants = ();
1734 %parameterdescs = ();
1735 %parametertypes = ();
1736 @parameterlist = ();
1737 %sections = ();
1738 @sectionlist = ();
1739 $prototype = "";
1741 $state = 0;
1744 sub process_state3_function($$) {
1745 my $x = shift;
1746 my $file = shift;
1748 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1750 if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#define/)) {
1751 # do nothing
1753 elsif ($x =~ /([^\{]*)/) {
1754 $prototype .= $1;
1756 if (($x =~ /\{/) || ($x =~ /\#define/) || ($x =~ /;/)) {
1757 $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
1758 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1759 $prototype =~ s@^\s+@@gos; # strip leading spaces
1760 dump_function($prototype,$file);
1761 reset_state();
1765 sub process_state3_type($$) {
1766 my $x = shift;
1767 my $file = shift;
1769 $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1770 $x =~ s@^\s+@@gos; # strip leading spaces
1771 $x =~ s@\s+$@@gos; # strip trailing spaces
1772 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1774 if ($x =~ /^#/) {
1775 # To distinguish preprocessor directive from regular declaration later.
1776 $x .= ";";
1779 while (1) {
1780 if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
1781 $prototype .= $1 . $2;
1782 ($2 eq '{') && $brcount++;
1783 ($2 eq '}') && $brcount--;
1784 if (($2 eq ';') && ($brcount == 0)) {
1785 dump_declaration($prototype,$file);
1786 reset_state();
1787 last;
1789 $x = $3;
1790 } else {
1791 $prototype .= $x;
1792 last;
1797 # xml_escape: replace <, >, and & in the text stream;
1799 # however, formatting controls that are generated internally/locally in the
1800 # kernel-doc script are not escaped here; instead, they begin life like
1801 # $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
1802 # are converted to their mnemonic-expected output, without the 4 * '\' & ':',
1803 # just before actual output; (this is done by local_unescape())
1804 sub xml_escape($) {
1805 my $text = shift;
1806 if (($output_mode eq "text") || ($output_mode eq "man")) {
1807 return $text;
1809 $text =~ s/\&/\\\\\\amp;/g;
1810 $text =~ s/\</\\\\\\lt;/g;
1811 $text =~ s/\>/\\\\\\gt;/g;
1812 return $text;
1815 # convert local escape strings to html
1816 # local escape strings look like: '\\\\menmonic:' (that's 4 backslashes)
1817 sub local_unescape($) {
1818 my $text = shift;
1819 if (($output_mode eq "text") || ($output_mode eq "man")) {
1820 return $text;
1822 $text =~ s/\\\\\\\\lt:/</g;
1823 $text =~ s/\\\\\\\\gt:/>/g;
1824 return $text;
1827 sub process_file($) {
1828 my $file;
1829 my $identifier;
1830 my $func;
1831 my $descr;
1832 my $initial_section_counter = $section_counter;
1834 if (defined($ENV{'SRCTREE'})) {
1835 $file = "$ENV{'SRCTREE'}" . "/" . "@_";
1837 else {
1838 $file = "@_";
1840 if (defined($source_map{$file})) {
1841 $file = $source_map{$file};
1844 if (!open(IN,"<$file")) {
1845 print STDERR "Error: Cannot open file $file\n";
1846 ++$errors;
1847 return;
1850 $section_counter = 0;
1851 while (<IN>) {
1852 if ($state == 0) {
1853 if (/$doc_start/o) {
1854 $state = 1; # next line is always the function name
1855 $in_doc_sect = 0;
1857 } elsif ($state == 1) { # this line is the function name (always)
1858 if (/$doc_block/o) {
1859 $state = 4;
1860 $contents = "";
1861 if ( $1 eq "" ) {
1862 $section = $section_intro;
1863 } else {
1864 $section = $1;
1867 elsif (/$doc_decl/o) {
1868 $identifier = $1;
1869 if (/\s*([\w\s]+?)\s*-/) {
1870 $identifier = $1;
1873 $state = 2;
1874 if (/-(.*)/) {
1875 # strip leading/trailing/multiple spaces
1876 $descr= $1;
1877 $descr =~ s/^\s*//;
1878 $descr =~ s/\s*$//;
1879 $descr =~ s/\s+/ /;
1880 $declaration_purpose = xml_escape($descr);
1881 } else {
1882 $declaration_purpose = "";
1884 if ($identifier =~ m/^struct/) {
1885 $decl_type = 'struct';
1886 } elsif ($identifier =~ m/^union/) {
1887 $decl_type = 'union';
1888 } elsif ($identifier =~ m/^enum/) {
1889 $decl_type = 'enum';
1890 } elsif ($identifier =~ m/^typedef/) {
1891 $decl_type = 'typedef';
1892 } else {
1893 $decl_type = 'function';
1896 if ($verbose) {
1897 print STDERR "Info(${file}:$.): Scanning doc for $identifier\n";
1899 } else {
1900 print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.",
1901 " - I thought it was a doc line\n";
1902 ++$warnings;
1903 $state = 0;
1905 } elsif ($state == 2) { # look for head: lines, and include content
1906 if (/$doc_sect/o) {
1907 $newsection = $1;
1908 $newcontents = $2;
1910 if ($contents ne "") {
1911 if (!$in_doc_sect && $verbose) {
1912 print STDERR "Warning(${file}:$.): contents before sections\n";
1913 ++$warnings;
1915 dump_section($section, xml_escape($contents));
1916 $section = $section_default;
1919 $in_doc_sect = 1;
1920 $contents = $newcontents;
1921 if ($contents ne "") {
1922 while ((substr($contents, 0, 1) eq " ") ||
1923 substr($contents, 0, 1) eq "\t") {
1924 $contents = substr($contents, 1);
1926 $contents .= "\n";
1928 $section = $newsection;
1929 } elsif (/$doc_end/) {
1931 if ($contents ne "") {
1932 dump_section($section, xml_escape($contents));
1933 $section = $section_default;
1934 $contents = "";
1937 $prototype = "";
1938 $state = 3;
1939 $brcount = 0;
1940 # print STDERR "end of doc comment, looking for prototype\n";
1941 } elsif (/$doc_content/) {
1942 # miguel-style comment kludge, look for blank lines after
1943 # @parameter line to signify start of description
1944 if ($1 eq "" &&
1945 ($section =~ m/^@/ || $section eq $section_context)) {
1946 dump_section($section, xml_escape($contents));
1947 $section = $section_default;
1948 $contents = "";
1949 } else {
1950 $contents .= $1."\n";
1952 } else {
1953 # i dont know - bad line? ignore.
1954 print STDERR "Warning(${file}:$.): bad line: $_";
1955 ++$warnings;
1957 } elsif ($state == 3) { # scanning for function '{' (end of prototype)
1958 if ($decl_type eq 'function') {
1959 process_state3_function($_, $file);
1960 } else {
1961 process_state3_type($_, $file);
1963 } elsif ($state == 4) {
1964 # Documentation block
1965 if (/$doc_block/) {
1966 dump_doc_section($section, xml_escape($contents));
1967 $contents = "";
1968 $function = "";
1969 %constants = ();
1970 %parameterdescs = ();
1971 %parametertypes = ();
1972 @parameterlist = ();
1973 %sections = ();
1974 @sectionlist = ();
1975 $prototype = "";
1976 if ( $1 eq "" ) {
1977 $section = $section_intro;
1978 } else {
1979 $section = $1;
1982 elsif (/$doc_end/)
1984 dump_doc_section($section, xml_escape($contents));
1985 $contents = "";
1986 $function = "";
1987 %constants = ();
1988 %parameterdescs = ();
1989 %parametertypes = ();
1990 @parameterlist = ();
1991 %sections = ();
1992 @sectionlist = ();
1993 $prototype = "";
1994 $state = 0;
1996 elsif (/$doc_content/)
1998 if ( $1 eq "" )
2000 $contents .= $blankline;
2002 else
2004 $contents .= $1 . "\n";
2009 if ($initial_section_counter == $section_counter) {
2010 print STDERR "Warning(${file}): no structured comments found\n";
2011 if ($output_mode eq "xml") {
2012 # The template wants at least one RefEntry here; make one.
2013 print "<refentry>\n";
2014 print " <refnamediv>\n";
2015 print " <refname>\n";
2016 print " ${file}\n";
2017 print " </refname>\n";
2018 print " <refpurpose>\n";
2019 print " Document generation inconsistency\n";
2020 print " </refpurpose>\n";
2021 print " </refnamediv>\n";
2022 print " <refsect1>\n";
2023 print " <title>\n";
2024 print " Oops\n";
2025 print " </title>\n";
2026 print " <warning>\n";
2027 print " <para>\n";
2028 print " The template for this document tried to insert\n";
2029 print " the structured comment from the file\n";
2030 print " <filename>${file}</filename> at this point,\n";
2031 print " but none was found.\n";
2032 print " This dummy section is inserted to allow\n";
2033 print " generation to continue.\n";
2034 print " </para>\n";
2035 print " </warning>\n";
2036 print " </refsect1>\n";
2037 print "</refentry>\n";