scripts/kernel-doc

   1 #!/usr/bin/perl -w
   2
   3 use strict;
   4
   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 ##                                                               ##
   9 ## #define enhancements by Armin Kuster <akuster@mvista.com>     ##
  10 ## Copyright (c) 2000 MontaVista Software, Inc.                  ##
  11 ##                                                               ##
  12 ## This software falls under the GNU General Public License.     ##
  13 ## Please read the COPYING file for more information             ##
  14
  15 # w.o. 03-11-2000: added the '-filelist' option.
  16
  17 # 18/01/2001 -  Cleanups
  18 #               Functions prototyped as foo(void) same as foo()
  19 #               Stop eval'ing where we don't need to.
  20 # -- huggie@earth.li
  21
  22 # 27/06/2001 -  Allowed whitespace after initial "/**" and
  23 #               allowed comments before function declarations.
  24 # -- Christian Kreibich <ck@whoop.org>
  25
  26 # Still to do:
  27 #       - add perldoc documentation
  28 #       - Look more closely at some of the scarier bits :)
  29
  30 # 26/05/2001 -  Support for separate source and object trees.
  31 #               Return error code.
  32 #               Keith Owens <kaos@ocs.com.au>
  33
  34 # 23/09/2001 - Added support for typedefs, structs, enums and unions
  35 #              Support for Context section; can be terminated using empty line
  36 #              Small fixes (like spaces vs. \s in regex)
  37 # -- Tim Jansen <tim@tjansen.de>
  38
  39
  40 #
  41 # This will read a 'c' file and scan for embedded comments in the
  42 # style of gnome comments (+minor extensions - see below).
  43 #
  44
  45 # Note: This only supports 'c'.
  46
  47 # usage:
  48 # kerneldoc [ -docbook | -html | -text | -man ]
  49 #           [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
  50 # or
  51 #           [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile
  52 #
  53 #  Set output format using one of -docbook -html -text or -man.  Default is man.
  54 #
  55 #  -function funcname
  56 #       If set, then only generate documentation for the given function(s).  All
  57 #       other functions are ignored.
  58 #
  59 #  -nofunction funcname
  60 #       If set, then only generate documentation for the other function(s).  All
  61 #       other functions are ignored. Cannot be used with -function together
  62 #       (yes thats a bug - perl hackers can fix it 8))
  63 #
  64 #  c files - list of 'c' files to process
  65 #
  66 #  All output goes to stdout, with errors to stderr.
  67
  68 #
  69 # format of comments.
  70 # In the following table, (...)? signifies optional structure.
  71 #                         (...)* signifies 0 or more structure elements
  72 # /**
  73 #  * function_name(:)? (- short description)?
  74 # (* @parameterx: (description of parameter x)?)*
  75 # (* a blank line)?
  76 #  * (Description:)? (Description of function)?
  77 #  * (section header: (section description)? )*
  78 #  (*)?*/
  79 #
  80 # So .. the trivial example would be:
  81 #
  82 # /**
  83 #  * my_function
  84 #  **/
  85 #
  86 # If the Description: header tag is ommitted, then there must be a blank line
  87 # after the last parameter specification.
  88 # e.g.
  89 # /**
  90 #  * my_function - does my stuff
  91 #  * @my_arg: its mine damnit
  92 #  *
  93 #  * Does my stuff explained.
  94 #  */
  95 #
  96 #  or, could also use:
  97 # /**
  98 #  * my_function - does my stuff
  99 #  * @my_arg: its mine damnit
 100 #  * Description: Does my stuff explained.
 101 #  */
 102 # etc.
 103 #
 104 # Beside functions you can also write documentation for structs, unions,
 105 # enums and typedefs. Instead of the function name you must write the name
 106 # of the declaration;  the struct/union/enum/typedef must always precede
 107 # the name. Nesting of declarations is not supported.
 108 # Use the argument mechanism to document members or constants. In
 109 # structs and unions you must declare one member per declaration
 110 # (comma-separated members are not allowed -  the parser does not support
 111 # this).
 112 # e.g.
 113 # /**
 114 #  * struct my_struct - short description
 115 #  * @a: first member
 116 #  * @b: second member
 117 #  *
 118 #  * Longer description
 119 #  */
 120 # struct my_struct {
 121 #     int a;
 122 #     int b;
 123 # };
 124 #
 125 # All descriptions can be multiline, except the short function description.
 126 #
 127 # You can also add additional sections. When documenting kernel functions you
 128 # should document the "Context:" of the function, e.g. whether the functions
 129 # can be called form interrupts. Unlike other sections you can end it with an
 130 # empty line.
 131 # Example-sections should contain the string EXAMPLE so that they are marked
 132 # appropriately in DocBook.
 133 #
 134 # Example:
 135 # /**
 136 #  * user_function - function that can only be called in user context
 137 #  * @a: some argument
 138 #  * Context: !in_interrupt()
 139 #  *
 140 #  * Some description
 141 #  * Example:
 142 #  *    user_function(22);
 143 #  */
 144 # ...
 145 #
 146 #
 147 # All descriptive text is further processed, scanning for the following special
 148 # patterns, which are highlighted appropriately.
 149 #
 150 # 'funcname()' - function
 151 # '$ENVVAR' - environmental variable
 152 # '&struct_name' - name of a structure (up to two words including 'struct')
 153 # '@parameter' - name of a parameter
 154 # '%CONST' - name of a constant.
 155
 156 my $errors = 0;
 157 my $warnings = 0;
 158
 159 # match expressions used to find embedded type information
 160 my $type_constant = '\%([-_\w]+)';
 161 my $type_func = '(\w+)\(\)';
 162 my $type_param = '\@(\w+)';
 163 my $type_struct = '\&((struct\s*)?[_\w]+)';
 164 my $type_env = '(\$\w+)';
 165
 166 # Output conversion substitutions.
 167 #  One for each output format
 168
 169 # these work fairly well
 170 my %highlights_html = ( $type_constant, "<i>\$1</i>",
 171                         $type_func, "<b>\$1</b>",
 172                         $type_struct, "<i>\$1</i>",
 173                         $type_param, "<tt><b>\$1</b></tt>" );
 174 my $blankline_html = "<p>";
 175
 176 # sgml, docbook format
 177 my %highlights_sgml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
 178                         $type_constant, "<constant>\$1</constant>",
 179                         $type_func, "<function>\$1</function>",
 180                         $type_struct, "<structname>\$1</structname>",
 181                         $type_env, "<envar>\$1</envar>",
 182                         $type_param, "<parameter>\$1</parameter>" );
 183 my $blankline_sgml = "</para><para>\n";
 184
 185 # gnome, docbook format
 186 my %highlights_gnome = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",
 187                          $type_func, "<function>\$1</function>",
 188                          $type_struct, "<structname>\$1</structname>",
 189                          $type_env, "<envar>\$1</envar>",
 190                          $type_param, "<parameter>\$1</parameter>" );
 191 my $blankline_gnome = "</para><para>\n";
 192
 193 # these are pretty rough
 194 my %highlights_man = ( $type_constant, "\$1",
 195                        $type_func, "\\\\fB\$1\\\\fP",
 196                        $type_struct, "\\\\fI\$1\\\\fP",
 197                        $type_param, "\\\\fI\$1\\\\fP" );
 198 my $blankline_man = "";
 199
 200 # text-mode
 201 my %highlights_text = ( $type_constant, "\$1",
 202                         $type_func, "\$1",
 203                         $type_struct, "\$1",
 204                         $type_param, "\$1" );
 205 my $blankline_text = "";
 206
 207
 208 sub usage {
 209     print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ]\n";
 210     print "         [ -function funcname [ -function funcname ...] ]\n";
 211     print "         [ -nofunction funcname [ -nofunction funcname ...] ]\n";
 212     print "         c source file(s) > outputfile\n";
 213     exit 1;
 214 }
 215
 216 # read arguments
 217 if ($#ARGV==-1) {
 218     usage();
 219 }
 220
 221 my $verbose = 0;
 222 my $output_mode = "man";
 223 my %highlights = %highlights_man;
 224 my $blankline = $blankline_man;
 225 my $modulename = "Kernel API";
 226 my $function_only = 0;
 227 my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
 228                 'July', 'August', 'September', 'October',
 229                 'November', 'December')[(localtime)[4]] .
 230   " " . ((localtime)[5]+1900);
 231
 232 # Essentially these are globals
 233 # They probably want to be tidied up made more localised or summat.
 234 # CAVEAT EMPTOR!  Some of the others I localised may not want to be which
 235 # could cause "use of undefined value" or other bugs.
 236 my ($function, %function_table,%parametertypes,$declaration_purpose);
 237 my ($type,$declaration_name,$return_type);
 238 my ($newsection,$newcontents,$prototype,$filelist, $brcount, %source_map);
 239
 240 # Generated docbook code is inserted in a template at a point where
 241 # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
 242 # http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
 243 # We keep track of number of generated entries and generate a dummy
 244 # if needs be to ensure the expanded template can be postprocessed
 245 # into html.
 246 my $section_counter = 0;
 247
 248 my $lineprefix="";
 249
 250 # states
 251 # 0 - normal code
 252 # 1 - looking for function name
 253 # 2 - scanning field start.
 254 # 3 - scanning prototype.
 255 # 4 - documentation block
 256 my $state;
 257
 258 #declaration types: can be
 259 # 'function', 'struct', 'union', 'enum', 'typedef'
 260 my $decl_type;
 261
 262 my $doc_special = "\@\%\$\&";
 263
 264 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
 265 my $doc_end = '\*/';
 266 my $doc_com = '\s*\*\s*';
 267 my $doc_decl = $doc_com.'(\w+)';
 268 my $doc_sect = $doc_com.'(['.$doc_special.']?[\w ]+):(.*)';
 269 my $doc_content = $doc_com.'(.*)';
 270 my $doc_block = $doc_com.'DOC:\s*(.*)?';
 271
 272 my %constants;
 273 my %parameterdescs;
 274 my @parameterlist;
 275 my %sections;
 276 my @sectionlist;
 277
 278 my $contents = "";
 279 my $section_default = "Description";    # default section
 280 my $section_intro = "Introduction";
 281 my $section = $section_default;
 282 my $section_context = "Context";
 283
 284 my $undescribed = "-- undescribed --";
 285
 286 reset_state();
 287
 288 while ($ARGV[0] =~ m/^-(.*)/) {
 289     my $cmd = shift @ARGV;
 290     if ($cmd eq "-html") {
 291         $output_mode = "html";
 292         %highlights = %highlights_html;
 293         $blankline = $blankline_html;
 294     } elsif ($cmd eq "-man") {
 295         $output_mode = "man";
 296         %highlights = %highlights_man;
 297         $blankline = $blankline_man;
 298     } elsif ($cmd eq "-text") {
 299         $output_mode = "text";
 300         %highlights = %highlights_text;
 301         $blankline = $blankline_text;
 302     } elsif ($cmd eq "-docbook") {
 303         $output_mode = "sgml";
 304         %highlights = %highlights_sgml;
 305         $blankline = $blankline_sgml;
 306     } elsif ($cmd eq "-gnome") {
 307         $output_mode = "gnome";
 308         %highlights = %highlights_gnome;
 309         $blankline = $blankline_gnome;
 310     } elsif ($cmd eq "-module") { # not needed for sgml, inherits from calling document
 311         $modulename = shift @ARGV;
 312     } elsif ($cmd eq "-function") { # to only output specific functions
 313         $function_only = 1;
 314         $function = shift @ARGV;
 315         $function_table{$function} = 1;
 316     } elsif ($cmd eq "-nofunction") { # to only output specific functions
 317         $function_only = 2;
 318         $function = shift @ARGV;
 319         $function_table{$function} = 1;
 320     } elsif ($cmd eq "-v") {
 321         $verbose = 1;
 322     } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
 323         usage();
 324     } elsif ($cmd eq '-filelist') {
 325             $filelist = shift @ARGV;
 326     }
 327 }
 328
 329
 330 # generate a sequence of code that will splice in highlighting information
 331 # using the s// operator.
 332 my $dohighlight = "";
 333 foreach my $pattern (keys %highlights) {
 334 #    print "scanning pattern $pattern ($highlights{$pattern})\n";
 335     $dohighlight .=  "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
 336 }
 337
 338 ##
 339 # dumps section contents to arrays/hashes intended for that purpose.
 340 #
 341 sub dump_section {
 342     my $name = shift;
 343     my $contents = join "\n", @_;
 344
 345     if ($name =~ m/$type_constant/) {
 346         $name = $1;
 347 #       print STDERR "constant section '$1' = '$contents'\n";
 348         $constants{$name} = $contents;
 349     } elsif ($name =~ m/$type_param/) {
 350 #       print STDERR "parameter def '$1' = '$contents'\n";
 351         $name = $1;
 352         $parameterdescs{$name} = $contents;
 353     } else {
 354 #       print STDERR "other section '$name' = '$contents'\n";
 355         $sections{$name} = $contents;
 356         push @sectionlist, $name;
 357     }
 358 }
 359
 360 ##
 361 # output function
 362 #
 363 # parameterdescs, a hash.
 364 #  function => "function name"
 365 #  parameterlist => @list of parameters
 366 #  parameterdescs => %parameter descriptions
 367 #  sectionlist => @list of sections
 368 #  sections => %descriont descriptions
 369 #
 370
 371 sub output_highlight {
 372     my $contents = join "\n",@_;
 373     my $line;
 374
 375 #   DEBUG
 376 #   if (!defined $contents) {
 377 #       use Carp;
 378 #       confess "output_highlight got called with no args?\n";
 379 #   }
 380
 381     eval $dohighlight;
 382     die $@ if $@;
 383     foreach $line (split "\n", $contents) {
 384       if ($line eq ""){
 385             print $lineprefix, $blankline;
 386         } else {
 387             $line =~ s/\\\\\\/\&/g;
 388             print $lineprefix, $line;
 389         }
 390         print "\n";
 391     }
 392 }
 393
 394 #output sections in html
 395 sub output_section_html(%) {
 396     my %args = %{$_[0]};
 397     my $section;
 398
 399     foreach $section (@{$args{'sectionlist'}}) {
 400         print "<h3>$section</h3>\n";
 401         print "<blockquote>\n";
 402         output_highlight($args{'sections'}{$section});
 403         print "</blockquote>\n";
 404     }
 405 }
 406
 407 # output enum in html
 408 sub output_enum_html(%) {
 409     my %args = %{$_[0]};
 410     my ($parameter);
 411     my $count;
 412     print "<h2>enum ".$args{'enum'}."</h2>\n";
 413
 414     print "<b>enum ".$args{'enum'}."</b> {<br>\n";
 415     $count = 0;
 416     foreach $parameter (@{$args{'parameterlist'}}) {
 417         print " <b>".$parameter."</b>";
 418         if ($count != $#{$args{'parameterlist'}}) {
 419             $count++;
 420             print ",\n";
 421         }
 422         print "<br>";
 423     }
 424     print "};<br>\n";
 425
 426     print "<h3>Constants</h3>\n";
 427     print "<dl>\n";
 428     foreach $parameter (@{$args{'parameterlist'}}) {
 429         print "<dt><b>".$parameter."</b>\n";
 430         print "<dd>";
 431         output_highlight($args{'parameterdescs'}{$parameter});
 432     }
 433     print "</dl>\n";
 434     output_section_html(@_);
 435     print "<hr>\n";
 436 }
 437
 438 # output tyepdef in html
 439 sub output_typedef_html(%) {
 440     my %args = %{$_[0]};
 441     my ($parameter);
 442     my $count;
 443     print "<h2>typedef ".$args{'typedef'}."</h2>\n";
 444
 445     print "<b>typedef ".$args{'typedef'}."</b>\n";
 446     output_section_html(@_);
 447     print "<hr>\n";
 448 }
 449
 450 # output struct in html
 451 sub output_struct_html(%) {
 452     my %args = %{$_[0]};
 453     my ($parameter);
 454
 455     print "<h2>".$args{'type'}." ".$args{'struct'}."</h2>\n";
 456     print "<b>".$args{'type'}." ".$args{'struct'}."</b> {<br>\n";
 457     foreach $parameter (@{$args{'parameterlist'}}) {
 458         ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
 459         $type = $args{'parametertypes'}{$parameter};
 460         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 461             # pointer-to-function
 462             print " <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
 463         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
 464             print " <i>$1</i> <b>$parameter</b>$2;<br>\n";
 465         } else {
 466             print " <i>$type</i> <b>$parameter</b>;<br>\n";
 467         }
 468     }
 469     print "};<br>\n";
 470
 471     print "<h3>Members</h3>\n";
 472     print "<dl>\n";
 473     foreach $parameter (@{$args{'parameterlist'}}) {
 474         ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
 475         print "<dt><b>".$parameter."</b>\n";
 476         print "<dd>";
 477         output_highlight($args{'parameterdescs'}{$parameter});
 478     }
 479     print "</dl>\n";
 480     output_section_html(@_);
 481     print "<hr>\n";
 482 }
 483
 484 # output function in html
 485 sub output_function_html(%) {
 486     my %args = %{$_[0]};
 487     my ($parameter, $section);
 488     my $count;
 489     print "<h2>Function</h2>\n";
 490
 491     print "<i>".$args{'functiontype'}."</i>\n";
 492     print "<b>".$args{'function'}."</b>\n";
 493     print "(";
 494     $count = 0;
 495     foreach $parameter (@{$args{'parameterlist'}}) {
 496         $type = $args{'parametertypes'}{$parameter};
 497         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 498             # pointer-to-function
 499             print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
 500         } else {
 501             print "<i>".$type."</i> <b>".$parameter."</b>";
 502         }
 503         if ($count != $#{$args{'parameterlist'}}) {
 504             $count++;
 505             print ",\n";
 506         }
 507     }
 508     print ")\n";
 509
 510     print "<h3>Arguments</h3>\n";
 511     print "<dl>\n";
 512     foreach $parameter (@{$args{'parameterlist'}}) {
 513         ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
 514         print "<dt><b>".$parameter."</b>\n";
 515         print "<dd>";
 516         output_highlight($args{'parameterdescs'}{$parameter});
 517     }
 518     print "</dl>\n";
 519     output_section_html(@_);
 520     print "<hr>\n";
 521 }
 522
 523 # output intro in html
 524 sub output_intro_html(%) {
 525     my %args = %{$_[0]};
 526     my ($parameter, $section);
 527     my $count;
 528
 529     foreach $section (@{$args{'sectionlist'}}) {
 530         print "<h3>$section</h3>\n";
 531         print "<ul>\n";
 532         output_highlight($args{'sections'}{$section});
 533         print "</ul>\n";
 534     }
 535     print "<hr>\n";
 536 }
 537
 538 sub output_section_sgml(%) {
 539     my %args = %{$_[0]};
 540     my $section;
 541     # print out each section
 542     $lineprefix="   ";
 543     foreach $section (@{$args{'sectionlist'}}) {
 544         print "<refsect1>\n <title>$section</title>\n <para>\n";
 545         if ($section =~ m/EXAMPLE/i) {
 546             print "<example><para>\n";
 547         }
 548         output_highlight($args{'sections'}{$section});
 549         if ($section =~ m/EXAMPLE/i) {
 550             print "</para></example>\n";
 551         }
 552         print " </para>\n</refsect1>\n";
 553     }
 554 }
 555
 556 # output function in sgml DocBook
 557 sub output_function_sgml(%) {
 558     my %args = %{$_[0]};
 559     my ($parameter, $section);
 560     my $count;
 561     my $id;
 562
 563     $id = "API-".$args{'function'};
 564     $id =~ s/[^A-Za-z0-9]/-/g;
 565
 566     print "<refentry>\n";
 567     print "<refmeta>\n";
 568     print "<refentrytitle><phrase id=\"$id\">".$args{'function'}."</phrase></refentrytitle>\n";
 569     print "</refmeta>\n";
 570     print "<refnamediv>\n";
 571     print " <refname>".$args{'function'}."</refname>\n";
 572     print " <refpurpose>\n";
 573     print "  ";
 574     output_highlight ($args{'purpose'});
 575     print " </refpurpose>\n";
 576     print "</refnamediv>\n";
 577
 578     print "<refsynopsisdiv>\n";
 579     print " <title>Synopsis</title>\n";
 580     print "  <funcsynopsis><funcprototype>\n";
 581     print "   <funcdef>".$args{'functiontype'}." ";
 582     print "<function>".$args{'function'}." </function></funcdef>\n";
 583
 584     $count = 0;
 585     if ($#{$args{'parameterlist'}} >= 0) {
 586         foreach $parameter (@{$args{'parameterlist'}}) {
 587             $type = $args{'parametertypes'}{$parameter};
 588             if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 589                 # pointer-to-function
 590                 print "   <paramdef>$1<parameter>$parameter</parameter>)\n";
 591                 print "     <funcparams>$2</funcparams></paramdef>\n";
 592             } else {
 593                 print "   <paramdef>".$type;
 594                 print " <parameter>$parameter</parameter></paramdef>\n";
 595             }
 596         }
 597     } else {
 598         print "  <void>\n";
 599     }
 600     print "  </funcprototype></funcsynopsis>\n";
 601     print "</refsynopsisdiv>\n";
 602
 603     # print parameters
 604     print "<refsect1>\n <title>Arguments</title>\n";
 605     if ($#{$args{'parameterlist'}} >= 0) {
 606         print " <variablelist>\n";
 607         foreach $parameter (@{$args{'parameterlist'}}) {
 608             print "  <varlistentry>\n   <term><parameter>$parameter</parameter></term>\n";
 609             print "   <listitem>\n    <para>\n";
 610             $lineprefix="     ";
 611             output_highlight($args{'parameterdescs'}{$parameter});
 612             print "    </para>\n   </listitem>\n  </varlistentry>\n";
 613         }
 614         print " </variablelist>\n";
 615     } else {
 616         print " <para>\n  None\n </para>\n";
 617     }
 618     print "</refsect1>\n";
 619
 620     output_section_sgml(@_);
 621     print "</refentry>\n\n";
 622 }
 623
 624 # output struct in sgml DocBook
 625 sub output_struct_sgml(%) {
 626     my %args = %{$_[0]};
 627     my ($parameter, $section);
 628     my $id;
 629
 630     $id = "API-struct-".$args{'struct'};
 631     $id =~ s/[^A-Za-z0-9]/-/g;
 632
 633     print "<refentry>\n";
 634     print "<refmeta>\n";
 635     print "<refentrytitle><phrase id=\"$id\">".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>\n";
 636     print "</refmeta>\n";
 637     print "<refnamediv>\n";
 638     print " <refname>".$args{'type'}." ".$args{'struct'}."</refname>\n";
 639     print " <refpurpose>\n";
 640     print "  ";
 641     output_highlight ($args{'purpose'});
 642     print " </refpurpose>\n";
 643     print "</refnamediv>\n";
 644
 645     print "<refsynopsisdiv>\n";
 646     print " <title>Synopsis</title>\n";
 647     print "  <programlisting>\n";
 648     print $args{'type'}." ".$args{'struct'}." {\n";
 649     foreach $parameter (@{$args{'parameterlist'}}) {
 650         defined($args{'parameterdescs'}{$parameter}) || next;
 651         ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
 652         $type = $args{'parametertypes'}{$parameter};
 653         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 654             # pointer-to-function
 655             print "  $1 $parameter) ($2);\n";
 656         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
 657             print "  $1 $parameter$2;\n";
 658         } else {
 659             print "  ".$type." ".$parameter.";\n";
 660         }
 661     }
 662     print "};";
 663     print "  </programlisting>\n";
 664     print "</refsynopsisdiv>\n";
 665
 666     print " <refsect1>\n";
 667     print "  <title>Members</title>\n";
 668
 669     print "  <variablelist>\n";
 670     foreach $parameter (@{$args{'parameterlist'}}) {
 671       defined($args{'parameterdescs'}{$parameter}) || next;
 672       ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
 673       print "    <varlistentry>";
 674       print "      <term>$parameter</term>\n";
 675       print "      <listitem><para>\n";
 676       output_highlight($args{'parameterdescs'}{$parameter});
 677       print "      </para></listitem>\n";
 678       print "    </varlistentry>\n";
 679     }
 680     print "  </variablelist>\n";
 681     print " </refsect1>\n";
 682
 683     output_section_sgml(@_);
 684
 685     print "</refentry>\n\n";
 686 }
 687
 688 # output enum in sgml DocBook
 689 sub output_enum_sgml(%) {
 690     my %args = %{$_[0]};
 691     my ($parameter, $section);
 692     my $count;
 693     my $id;
 694
 695     $id = "API-enum-".$args{'enum'};
 696     $id =~ s/[^A-Za-z0-9]/-/g;
 697
 698     print "<refentry>\n";
 699     print "<refmeta>\n";
 700     print "<refentrytitle><phrase id=\"$id\">enum ".$args{'enum'}."</phrase></refentrytitle>\n";
 701     print "</refmeta>\n";
 702     print "<refnamediv>\n";
 703     print " <refname>enum ".$args{'enum'}."</refname>\n";
 704     print " <refpurpose>\n";
 705     print "  ";
 706     output_highlight ($args{'purpose'});
 707     print " </refpurpose>\n";
 708     print "</refnamediv>\n";
 709
 710     print "<refsynopsisdiv>\n";
 711     print " <title>Synopsis</title>\n";
 712     print "  <programlisting>\n";
 713     print "enum ".$args{'enum'}." {\n";
 714     $count = 0;
 715     foreach $parameter (@{$args{'parameterlist'}}) {
 716         print "  $parameter";
 717         if ($count != $#{$args{'parameterlist'}}) {
 718             $count++;
 719             print ",";
 720         }
 721         print "\n";
 722     }
 723     print "};";
 724     print "  </programlisting>\n";
 725     print "</refsynopsisdiv>\n";
 726
 727     print "<refsect1>\n";
 728     print " <title>Constants</title>\n";
 729     print "  <variablelist>\n";
 730     foreach $parameter (@{$args{'parameterlist'}}) {
 731       print "    <varlistentry>";
 732       print "      <term>$parameter</term>\n";
 733       print "      <listitem><para>\n";
 734       output_highlight($args{'parameterdescs'}{$parameter});
 735       print "      </para></listitem>\n";
 736       print "    </varlistentry>\n";
 737     }
 738     print "  </variablelist>\n";
 739     print "</refsect1>\n";
 740
 741     output_section_sgml(@_);
 742
 743     print "</refentry>\n\n";
 744 }
 745
 746 # output typedef in sgml DocBook
 747 sub output_typedef_sgml(%) {
 748     my %args = %{$_[0]};
 749     my ($parameter, $section);
 750     my $id;
 751
 752     $id = "API-typedef-".$args{'typedef'};
 753     $id =~ s/[^A-Za-z0-9]/-/g;
 754
 755     print "<refentry>\n";
 756     print "<refmeta>\n";
 757     print "<refentrytitle><phrase id=\"$id\">typedef ".$args{'typedef'}."</phrase></refentrytitle>\n";
 758     print "</refmeta>\n";
 759     print "<refnamediv>\n";
 760     print " <refname>typedef ".$args{'typedef'}."</refname>\n";
 761     print " <refpurpose>\n";
 762     print "  ";
 763     output_highlight ($args{'purpose'});
 764     print " </refpurpose>\n";
 765     print "</refnamediv>\n";
 766
 767     print "<refsynopsisdiv>\n";
 768     print " <title>Synopsis</title>\n";
 769     print "  <synopsis>typedef ".$args{'typedef'}.";</synopsis>\n";
 770     print "</refsynopsisdiv>\n";
 771
 772     output_section_sgml(@_);
 773
 774     print "</refentry>\n\n";
 775 }
 776
 777 # output in sgml DocBook
 778 sub output_intro_sgml(%) {
 779     my %args = %{$_[0]};
 780     my ($parameter, $section);
 781     my $count;
 782
 783     my $id = $args{'module'};
 784     $id =~ s/[^A-Za-z0-9]/-/g;
 785
 786     # print out each section
 787     $lineprefix="   ";
 788     foreach $section (@{$args{'sectionlist'}}) {
 789         print "<refsect1>\n <title>$section</title>\n <para>\n";
 790         if ($section =~ m/EXAMPLE/i) {
 791             print "<example><para>\n";
 792         }
 793         output_highlight($args{'sections'}{$section});
 794         if ($section =~ m/EXAMPLE/i) {
 795             print "</para></example>\n";
 796         }
 797         print " </para>\n</refsect1>\n";
 798     }
 799
 800     print "\n\n";
 801 }
 802
 803 # output in sgml DocBook
 804 sub output_function_gnome {
 805     my %args = %{$_[0]};
 806     my ($parameter, $section);
 807     my $count;
 808     my $id;
 809
 810     $id = $args{'module'}."-".$args{'function'};
 811     $id =~ s/[^A-Za-z0-9]/-/g;
 812
 813     print "<sect2>\n";
 814     print " <title id=\"$id\">".$args{'function'}."</title>\n";
 815
 816     print "  <funcsynopsis>\n";
 817     print "   <funcdef>".$args{'functiontype'}." ";
 818     print "<function>".$args{'function'}." ";
 819     print "</function></funcdef>\n";
 820
 821     $count = 0;
 822     if ($#{$args{'parameterlist'}} >= 0) {
 823         foreach $parameter (@{$args{'parameterlist'}}) {
 824             $type = $args{'parametertypes'}{$parameter};
 825             if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 826                 # pointer-to-function
 827                 print "   <paramdef>$1 <parameter>$parameter</parameter>)\n";
 828                 print "     <funcparams>$2</funcparams></paramdef>\n";
 829             } else {
 830                 print "   <paramdef>".$type;
 831                 print " <parameter>$parameter</parameter></paramdef>\n";
 832             }
 833         }
 834     } else {
 835         print "  <void>\n";
 836     }
 837     print "  </funcsynopsis>\n";
 838     if ($#{$args{'parameterlist'}} >= 0) {
 839         print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
 840         print "<tgroup cols=\"2\">\n";
 841         print "<colspec colwidth=\"2*\">\n";
 842         print "<colspec colwidth=\"8*\">\n";
 843         print "<tbody>\n";
 844         foreach $parameter (@{$args{'parameterlist'}}) {
 845             print "  <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
 846             print "   <entry>\n";
 847             $lineprefix="     ";
 848             output_highlight($args{'parameterdescs'}{$parameter});
 849             print "    </entry></row>\n";
 850         }
 851         print " </tbody></tgroup></informaltable>\n";
 852     } else {
 853         print " <para>\n  None\n </para>\n";
 854     }
 855
 856     # print out each section
 857     $lineprefix="   ";
 858     foreach $section (@{$args{'sectionlist'}}) {
 859         print "<simplesect>\n <title>$section</title>\n";
 860         if ($section =~ m/EXAMPLE/i) {
 861             print "<example><programlisting>\n";
 862         } else {
 863         }
 864         print "<para>\n";
 865         output_highlight($args{'sections'}{$section});
 866         print "</para>\n";
 867         if ($section =~ m/EXAMPLE/i) {
 868             print "</programlisting></example>\n";
 869         } else {
 870         }
 871         print " </simplesect>\n";
 872     }
 873
 874     print "</sect2>\n\n";
 875 }
 876
 877 ##
 878 # output function in man
 879 sub output_function_man(%) {
 880     my %args = %{$_[0]};
 881     my ($parameter, $section);
 882     my $count;
 883
 884     print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
 885
 886     print ".SH NAME\n";
 887     print $args{'function'}." \\- ".$args{'purpose'}."\n";
 888
 889     print ".SH SYNOPSIS\n";
 890     print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n";
 891     $count = 0;
 892     my $parenth = "(";
 893     my $post = ",";
 894     foreach my $parameter (@{$args{'parameterlist'}}) {
 895         if ($count == $#{$args{'parameterlist'}}) {
 896             $post = ");";
 897         }
 898         $type = $args{'parametertypes'}{$parameter};
 899         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 900             # pointer-to-function
 901             print ".BI \"".$parenth.$1."\" ".$parameter." \") (".$2.")".$post."\"\n";
 902         } else {
 903             $type =~ s/([^\*])$/$1 /;
 904             print ".BI \"".$parenth.$type."\" ".$parameter." \"".$post."\"\n";
 905         }
 906         $count++;
 907         $parenth = "";
 908     }
 909
 910     print ".SH ARGUMENTS\n";
 911     foreach $parameter (@{$args{'parameterlist'}}) {
 912         print ".IP \"".$parameter."\" 12\n";
 913         output_highlight($args{'parameterdescs'}{$parameter});
 914     }
 915     foreach $section (@{$args{'sectionlist'}}) {
 916         print ".SH \"", uc $section, "\"\n";
 917         output_highlight($args{'sections'}{$section});
 918     }
 919 }
 920
 921 ##
 922 # output enum in man
 923 sub output_enum_man(%) {
 924     my %args = %{$_[0]};
 925     my ($parameter, $section);
 926     my $count;
 927
 928     print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
 929
 930     print ".SH NAME\n";
 931     print "enum ".$args{'enum'}." \\- ".$args{'purpose'}."\n";
 932
 933     print ".SH SYNOPSIS\n";
 934     print "enum ".$args{'enum'}." {\n";
 935     $count = 0;
 936     foreach my $parameter (@{$args{'parameterlist'}}) {
 937         print ".br\n.BI \"    $parameter\"\n";
 938         if ($count == $#{$args{'parameterlist'}}) {
 939             print "\n};\n";
 940             last;
 941         }
 942         else {
 943             print ", \n.br\n";
 944         }
 945         $count++;
 946     }
 947
 948     print ".SH Constants\n";
 949     foreach $parameter (@{$args{'parameterlist'}}) {
 950         print ".IP \"".$parameter."\" 12\n";
 951         output_highlight($args{'parameterdescs'}{$parameter});
 952     }
 953     foreach $section (@{$args{'sectionlist'}}) {
 954         print ".SH \"$section\"\n";
 955         output_highlight($args{'sections'}{$section});
 956     }
 957 }
 958
 959 ##
 960 # output struct in man
 961 sub output_struct_man(%) {
 962     my %args = %{$_[0]};
 963     my ($parameter, $section);
 964
 965     print ".TH \"$args{'module'}\" 9 \"".$args{'type'}." ".$args{'struct'}."\" \"$man_date\" \"API Manual\" LINUX\n";
 966
 967     print ".SH NAME\n";
 968     print $args{'type'}." ".$args{'struct'}." \\- ".$args{'purpose'}."\n";
 969
 970     print ".SH SYNOPSIS\n";
 971     print $args{'type'}." ".$args{'struct'}." {\n";
 972
 973     foreach my $parameter (@{$args{'parameterlist'}}) {
 974         ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
 975         print "\n.br\n";
 976         $type = $args{'parametertypes'}{$parameter};
 977         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 978             # pointer-to-function
 979             print ".BI \"    ".$1."\" ".$parameter." \") (".$2.")"."\"\n;\n";
 980         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
 981             print ".BI \"    ".$1."\" ".$parameter.$2." \""."\"\n;\n";
 982         } else {
 983             $type =~ s/([^\*])$/$1 /;
 984             print ".BI \"    ".$type."\" ".$parameter." \""."\"\n;\n";
 985         }
 986         print "\n.br\n";
 987     }
 988     print "};\n.br\n";
 989
 990     print ".SH Arguments\n";
 991     foreach $parameter (@{$args{'parameterlist'}}) {
 992         ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
 993         print ".IP \"".$parameter."\" 12\n";
 994         output_highlight($args{'parameterdescs'}{$parameter});
 995     }
 996     foreach $section (@{$args{'sectionlist'}}) {
 997         print ".SH \"$section\"\n";
 998         output_highlight($args{'sections'}{$section});
 999     }
1000 }
1001
1002 ##
1003 # output typedef in man
1004 sub output_typedef_man(%) {
1005     my %args = %{$_[0]};
1006     my ($parameter, $section);
1007
1008     print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
1009
1010     print ".SH NAME\n";
1011     print "typedef ".$args{'typedef'}." \\- ".$args{'purpose'}."\n";
1012
1013     foreach $section (@{$args{'sectionlist'}}) {
1014         print ".SH \"$section\"\n";
1015         output_highlight($args{'sections'}{$section});
1016     }
1017 }
1018
1019 sub output_intro_man(%) {
1020     my %args = %{$_[0]};
1021     my ($parameter, $section);
1022     my $count;
1023
1024     print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
1025
1026     foreach $section (@{$args{'sectionlist'}}) {
1027         print ".SH \"$section\"\n";
1028         output_highlight($args{'sections'}{$section});
1029     }
1030 }
1031
1032 ##
1033 # output in text
1034 sub output_function_text(%) {
1035     my %args = %{$_[0]};
1036     my ($parameter, $section);
1037
1038     print "Function:\n\n";
1039     my $start=$args{'functiontype'}." ".$args{'function'}." (";
1040     print $start;
1041     my $count = 0;
1042     foreach my $parameter (@{$args{'parameterlist'}}) {
1043         $type = $args{'parametertypes'}{$parameter};
1044         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1045             # pointer-to-function
1046             print $1.$parameter.") (".$2;
1047         } else {
1048             print $type." ".$parameter;
1049         }
1050         if ($count != $#{$args{'parameterlist'}}) {
1051             $count++;
1052             print ",\n";
1053             print " " x length($start);
1054         } else {
1055             print ");\n\n";
1056         }
1057     }
1058
1059     print "Arguments:\n\n";
1060     foreach $parameter (@{$args{'parameterlist'}}) {
1061         print $parameter."\n\t".$args{'parameterdescs'}{$parameter}."\n";
1062     }
1063     output_section_text(@_);
1064 }
1065
1066 #output sections in text
1067 sub output_section_text(%) {
1068     my %args = %{$_[0]};
1069     my $section;
1070
1071     print "\n";
1072     foreach $section (@{$args{'sectionlist'}}) {
1073         print "$section:\n\n";
1074         output_highlight($args{'sections'}{$section});
1075     }
1076     print "\n\n";
1077 }
1078
1079 # output enum in text
1080 sub output_enum_text(%) {
1081     my %args = %{$_[0]};
1082     my ($parameter);
1083     my $count;
1084     print "Enum:\n\n";
1085
1086     print "enum ".$args{'enum'}." {\n";
1087     $count = 0;
1088     foreach $parameter (@{$args{'parameterlist'}}) {
1089         print "\t$parameter";
1090         if ($count != $#{$args{'parameterlist'}}) {
1091             $count++;
1092             print ",";
1093         }
1094         print "\n";
1095     }
1096     print "};\n\n";
1097
1098     print "Constants:\n\n";
1099     foreach $parameter (@{$args{'parameterlist'}}) {
1100         print "$parameter\n\t";
1101         print $args{'parameterdescs'}{$parameter}."\n";
1102     }
1103
1104     output_section_text(@_);
1105 }
1106
1107 # output typedef in text
1108 sub output_typedef_text(%) {
1109     my %args = %{$_[0]};
1110     my ($parameter);
1111     my $count;
1112     print "Typedef:\n\n";
1113
1114     print "typedef ".$args{'typedef'}."\n";
1115     output_section_text(@_);
1116 }
1117
1118 # output struct as text
1119 sub output_struct_text(%) {
1120     my %args = %{$_[0]};
1121     my ($parameter);
1122
1123     print $args{'type'}." ".$args{'struct'}.":\n\n";
1124     print $args{'type'}." ".$args{'struct'}." {\n";
1125     foreach $parameter (@{$args{'parameterlist'}}) {
1126         ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
1127         $type = $args{'parametertypes'}{$parameter};
1128         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1129             # pointer-to-function
1130             print "\t$1 $parameter) ($2);\n";
1131         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1132             print "\t$1 $parameter$2;\n";
1133         } else {
1134             print "\t".$type." ".$parameter.";\n";
1135         }
1136     }
1137     print "};\n\n";
1138
1139     print "Members:\n\n";
1140     foreach $parameter (@{$args{'parameterlist'}}) {
1141         ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
1142         print "$parameter\n\t";
1143         print $args{'parameterdescs'}{$parameter}."\n";
1144     }
1145     print "\n";
1146     output_section_text(@_);
1147 }
1148
1149 sub output_intro_text(%) {
1150     my %args = %{$_[0]};
1151     my ($parameter, $section);
1152
1153     foreach $section (@{$args{'sectionlist'}}) {
1154         print " $section:\n";
1155         print "    -> ";
1156         output_highlight($args{'sections'}{$section});
1157     }
1158 }
1159
1160 ##
1161 # generic output function for typedefs
1162 sub output_declaration {
1163     no strict 'refs';
1164     my $name = shift;
1165     my $functype = shift;
1166     my $func = "output_${functype}_$output_mode";
1167     if (($function_only==0) ||
1168         ( $function_only == 1 && defined($function_table{$name})) ||
1169         ( $function_only == 2 && !defined($function_table{$name})))
1170     {
1171         &$func(@_);
1172         $section_counter++;
1173     }
1174 }
1175
1176 ##
1177 # generic output function - calls the right one based
1178 # on current output mode.
1179 sub output_intro {
1180     no strict 'refs';
1181     my $func = "output_intro_".$output_mode;
1182     &$func(@_);
1183     $section_counter++;
1184 }
1185
1186 ##
1187 # takes a declaration (struct, union, enum, typedef) and
1188 # invokes the right handler. NOT called for functions.
1189 sub dump_declaration($$) {
1190     no strict 'refs';
1191     my ($prototype, $file) = @_;
1192     my $func = "dump_".$decl_type;
1193     &$func(@_);
1194 }
1195
1196 sub dump_union($$) {
1197     dump_struct(@_);
1198 }
1199
1200 sub dump_struct($$) {
1201     my $x = shift;
1202     my $file = shift;
1203
1204     if ($x =~/(struct|union)\s+(\w+)\s*{(.*)}/) {
1205         $declaration_name = $2;
1206         my $members = $3;
1207
1208         # ignore embedded structs or unions
1209         $members =~ s/{.*?}//g;
1210
1211         create_parameterlist($members, ';', $file);
1212
1213         output_declaration($declaration_name,
1214                            'struct',
1215                            {'struct' => $declaration_name,
1216                             'module' => $modulename,
1217                             'parameterlist' => \@parameterlist,
1218                             'parameterdescs' => \%parameterdescs,
1219                             'parametertypes' => \%parametertypes,
1220                             'sectionlist' => \@sectionlist,
1221                             'sections' => \%sections,
1222                             'purpose' => $declaration_purpose,
1223                             'type' => $decl_type
1224                            });
1225     }
1226     else {
1227         print STDERR "Error(${file}:$.): Cannot parse struct or union!\n";
1228         ++$errors;
1229     }
1230 }
1231
1232 sub dump_enum($$) {
1233     my $x = shift;
1234     my $file = shift;
1235
1236     if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
1237         $declaration_name = $1;
1238         my $members = $2;
1239
1240         foreach my $arg (split ',', $members) {
1241             $arg =~ s/^\s*(\w+).*/$1/;
1242             push @parameterlist, $arg;
1243             if (!$parameterdescs{$arg}) {
1244                 $parameterdescs{$arg} = $undescribed;
1245                 print STDERR "Warning(${file}:$.): Enum value '$arg' ".
1246                     "not described in enum '$declaration_name'\n";
1247             }
1248
1249         }
1250
1251         output_declaration($declaration_name,
1252                            'enum',
1253                            {'enum' => $declaration_name,
1254                             'module' => $modulename,
1255                             'parameterlist' => \@parameterlist,
1256                             'parameterdescs' => \%parameterdescs,
1257                             'sectionlist' => \@sectionlist,
1258                             'sections' => \%sections,
1259                             'purpose' => $declaration_purpose
1260                            });
1261     }
1262     else {
1263         print STDERR "Error(${file}:$.): Cannot parse enum!\n";
1264         ++$errors;
1265     }
1266 }
1267
1268 sub dump_typedef($$) {
1269     my $x = shift;
1270     my $file = shift;
1271
1272     while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
1273         $x =~ s/\(*.\)\s*;$/;/;
1274         $x =~ s/\[*.\]\s*;$/;/;
1275     }
1276
1277     if ($x =~ /typedef.*\s+(\w+)\s*;/) {
1278         $declaration_name = $1;
1279
1280         output_declaration($declaration_name,
1281                            'typedef',
1282                            {'typedef' => $declaration_name,
1283                             'module' => $modulename,
1284                             'sectionlist' => \@sectionlist,
1285                             'sections' => \%sections,
1286                             'purpose' => $declaration_purpose
1287                            });
1288     }
1289     else {
1290         print STDERR "Error(${file}:$.): Cannot parse typedef!\n";
1291         ++$errors;
1292     }
1293 }
1294
1295 sub create_parameterlist($$$) {
1296     my $args = shift;
1297     my $splitter = shift;
1298     my $file = shift;
1299     my $type;
1300     my $param;
1301
1302     while ($args =~ /(\([^\),]+),/) {
1303         $args =~ s/(\([^\),]+),/$1#/g;
1304     }
1305
1306     foreach my $arg (split($splitter, $args)) {
1307         # strip comments
1308         $arg =~ s/\/\*.*\*\///;
1309         # strip leading/trailing spaces
1310         $arg =~ s/^\s*//;
1311         $arg =~ s/\s*$//;
1312         $arg =~ s/\s+/ /;
1313
1314         if ($arg =~ m/\(/) {
1315             # pointer-to-function
1316             $arg =~ tr/#/,/;
1317             $arg =~ m/[^\(]+\(\*([^\)]+)\)/;
1318             $param = $1;
1319             $type = $arg;
1320             $type =~ s/([^\(]+\(\*)$param/$1/;
1321         } else {
1322             # evil magic to get fixed array parameters to work
1323             $arg =~ s/(.+\s+)(.+)\[.*/$1* $2/;
1324             my @args = split('\s', $arg);
1325
1326             $param = pop @args;
1327             if ($param =~ m/^(\*+)(.*)/) {
1328                 $param = $2;
1329                 push @args, $1;
1330             }
1331             elsif ($param =~ m/(.*?)\s*:\s*(\d+)/) {
1332                 $param = $1;
1333                 push @args, ":$2";
1334             }
1335             $type = join " ", @args;
1336         }
1337
1338         if ($type eq "" && $param eq "...")
1339         {
1340             $type="...";
1341             $param="...";
1342             $parameterdescs{"..."} = "variable arguments";
1343         }
1344         elsif ($type eq "" && ($param eq "" or $param eq "void"))
1345         {
1346             $type="";
1347             $param="void";
1348             $parameterdescs{void} = "no arguments";
1349         }
1350         if (defined $type && $type && !defined $parameterdescs{$param}) {
1351             $parameterdescs{$param} = $undescribed;
1352
1353             if (($type eq 'function') || ($type eq 'enum')) {
1354                 print STDERR "Warning(${file}:$.): Function parameter ".
1355                     "or member '$param' not " .
1356                     "described in '$declaration_name'\n";
1357             }
1358             print STDERR "Warning(${file}:$.):".
1359                          " No description found for parameter '$param'\n";
1360             ++$warnings;
1361         }
1362
1363         push @parameterlist, $param;
1364         $parametertypes{$param} = $type;
1365     }
1366 }
1367
1368 ##
1369 # takes a function prototype and the name of the current file being
1370 # processed and spits out all the details stored in the global
1371 # arrays/hashes.
1372 sub dump_function($$) {
1373     my $prototype = shift;
1374     my $file = shift;
1375
1376     $prototype =~ s/^static +//;
1377     $prototype =~ s/^extern +//;
1378     $prototype =~ s/^inline +//;
1379     $prototype =~ s/^__inline__ +//;
1380     $prototype =~ s/^#define +//; #ak added
1381     $prototype =~ s/__attribute__ \(\([a-z,]*\)\)//;
1382
1383     # Yes, this truly is vile.  We are looking for:
1384     # 1. Return type (may be nothing if we're looking at a macro)
1385     # 2. Function name
1386     # 3. Function parameters.
1387     #
1388     # All the while we have to watch out for function pointer parameters
1389     # (which IIRC is what the two sections are for), C types (these
1390     # regexps don't even start to express all the possibilities), and
1391     # so on.
1392     #
1393     # If you mess with these regexps, it's a good idea to check that
1394     # the following functions' documentation still comes out right:
1395     # - parport_register_device (function pointer parameters)
1396     # - atomic_set (macro)
1397     # - pci_match_device (long return type)
1398
1399     if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1400         $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1401         $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1402         $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1403         $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1404         $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1405         $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1406         $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1407         $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1408         $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1409         $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1410         $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1411         $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1412         $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/)  {
1413         $return_type = $1;
1414         $declaration_name = $2;
1415         my $args = $3;
1416
1417         create_parameterlist($args, ',', $file);
1418     } else {
1419         print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n";
1420         ++$errors;
1421         return;
1422     }
1423
1424     output_declaration($declaration_name,
1425                        'function',
1426                        {'function' => $declaration_name,
1427                         'module' => $modulename,
1428                         'functiontype' => $return_type,
1429                         'parameterlist' => \@parameterlist,
1430                         'parameterdescs' => \%parameterdescs,
1431                         'parametertypes' => \%parametertypes,
1432                         'sectionlist' => \@sectionlist,
1433                         'sections' => \%sections,
1434                         'purpose' => $declaration_purpose
1435                        });
1436 }
1437
1438 sub process_file($);
1439
1440 # Read the file that maps relative names to absolute names for
1441 # separate source and object directories and for shadow trees.
1442 if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
1443         my ($relname, $absname);
1444         while(<SOURCE_MAP>) {
1445                 chop();
1446                 ($relname, $absname) = (split())[0..1];
1447                 $relname =~ s:^/+::;
1448                 $source_map{$relname} = $absname;
1449         }
1450         close(SOURCE_MAP);
1451 }
1452
1453 if ($filelist) {
1454         open(FLIST,"<$filelist") or die "Can't open file list $filelist";
1455         while(<FLIST>) {
1456                 chop;
1457                 process_file($_);
1458         }
1459 }
1460
1461 foreach (@ARGV) {
1462     chomp;
1463     process_file($_);
1464 }
1465 if ($verbose && $errors) {
1466   print STDERR "$errors errors\n";
1467 }
1468 if ($verbose && $warnings) {
1469   print STDERR "$warnings warnings\n";
1470 }
1471
1472 exit($errors);
1473
1474 sub reset_state {
1475     $function = "";
1476     %constants = ();
1477     %parameterdescs = ();
1478     %parametertypes = ();
1479     @parameterlist = ();
1480     %sections = ();
1481     @sectionlist = ();
1482     $prototype = "";
1483
1484     $state = 0;
1485 }
1486
1487 sub process_state3_function($$) {
1488     my $x = shift;
1489     my $file = shift;
1490
1491     if ($x =~ m#\s*/\*\s+MACDOC\s*#io) {
1492         # do nothing
1493     }
1494     elsif ($x =~ /([^\{]*)/) {
1495         $prototype .= $1;
1496     }
1497     if (($x =~ /\{/) || ($x =~ /\#/) || ($x =~ /;/)) {
1498         $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
1499         $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1500         $prototype =~ s@^\s+@@gos; # strip leading spaces
1501         dump_function($prototype,$file);
1502         reset_state();
1503     }
1504 }
1505
1506 sub process_state3_type($$) {
1507     my $x = shift;
1508     my $file = shift;
1509
1510     $x =~ s@/\*.*?\*/@@gos;     # strip comments.
1511     $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1512     $x =~ s@^\s+@@gos; # strip leading spaces
1513     $x =~ s@\s+$@@gos; # strip trailing spaces
1514
1515     while (1) {
1516         if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
1517             $prototype .= $1 . $2;
1518             ($2 eq '{') && $brcount++;
1519             ($2 eq '}') && $brcount--;
1520             if (($2 eq ';') && ($brcount == 0)) {
1521                 dump_declaration($prototype,$file);
1522                 reset_state();
1523                 last;
1524             }
1525             $x = $3;
1526         } else {
1527             $prototype .= $x;
1528             last;
1529         }
1530     }
1531 }
1532
1533 sub process_file($) {
1534     my ($file) = @_;
1535     my $identifier;
1536     my $func;
1537     my $initial_section_counter = $section_counter;
1538
1539     if (defined($source_map{$file})) {
1540         $file = $source_map{$file};
1541     }
1542
1543     if (!open(IN,"<$file")) {
1544         print STDERR "Error: Cannot open file $file\n";
1545         ++$errors;
1546         return;
1547     }
1548
1549     $section_counter = 0;
1550     while (<IN>) {
1551         if ($state == 0) {
1552             if (/$doc_start/o) {
1553                 $state = 1;             # next line is always the function name
1554             }
1555         } elsif ($state == 1) { # this line is the function name (always)
1556             if (/$doc_block/o) {
1557                 $state = 4;
1558                 $contents = "";
1559                 if ( $1 eq "" ) {
1560                         $section = $section_intro;
1561                 } else {
1562                         $section = $1;
1563                 }
1564             }
1565             elsif (/$doc_decl/o) {
1566                 $identifier = $1;
1567                 if (/\s*([\w\s]+?)\s*-/) {
1568                     $identifier = $1;
1569                 }
1570
1571                 $state = 2;
1572                 if (/-(.*)/) {
1573                     $declaration_purpose = $1;
1574                 } else {
1575                     $declaration_purpose = "";
1576                 }
1577                 if ($identifier =~ m/^struct/) {
1578                     $decl_type = 'struct';
1579                 } elsif ($identifier =~ m/^union/) {
1580                     $decl_type = 'union';
1581                 } elsif ($identifier =~ m/^enum/) {
1582                     $decl_type = 'enum';
1583                 } elsif ($identifier =~ m/^typedef/) {
1584                     $decl_type = 'typedef';
1585                 } else {
1586                     $decl_type = 'function';
1587                 }
1588
1589                 if ($verbose) {
1590                     print STDERR "Info(${file}:$.): Scanning doc for $identifier\n";
1591                 }
1592             } else {
1593                 print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.",
1594                 " - I thought it was a doc line\n";
1595                 ++$warnings;
1596                 $state = 0;
1597             }
1598         } elsif ($state == 2) { # look for head: lines, and include content
1599             if (/$doc_sect/o) {
1600                 $newsection = $1;
1601                 $newcontents = $2;
1602
1603                 if ($contents ne "") {
1604                     $contents =~ s/\&/\\\\\\amp;/g;
1605                     $contents =~ s/\</\\\\\\lt;/g;
1606                     $contents =~ s/\>/\\\\\\gt;/g;
1607                     dump_section($section, $contents);
1608                     $section = $section_default;
1609                 }
1610
1611                 $contents = $newcontents;
1612                 if ($contents ne "") {
1613                     $contents .= "\n";
1614                 }
1615                 $section = $newsection;
1616             } elsif (/$doc_end/) {
1617
1618                 if ($contents ne "") {
1619                     $contents =~ s/\&/\\\\\\amp;/g;
1620                     $contents =~ s/\</\\\\\\lt;/g;
1621                     $contents =~ s/\>/\\\\\\gt;/g;
1622                     dump_section($section, $contents);
1623                     $section = $section_default;
1624                     $contents = "";
1625                 }
1626
1627                 $prototype = "";
1628                 $state = 3;
1629                 $brcount = 0;
1630 #           print STDERR "end of doc comment, looking for prototype\n";
1631             } elsif (/$doc_content/) {
1632                 # miguel-style comment kludge, look for blank lines after
1633                 # @parameter line to signify start of description
1634                 if ($1 eq "" &&
1635                         ($section =~ m/^@/ || $section eq $section_context)) {
1636                     $contents =~ s/\&/\\\\\\amp;/g;
1637                     $contents =~ s/\</\\\\\\lt;/g;
1638                     $contents =~ s/\>/\\\\\\gt;/g;
1639                     dump_section($section, $contents);
1640                     $section = $section_default;
1641                     $contents = "";
1642                 } else {
1643                     $contents .= $1."\n";
1644                 }
1645             } else {
1646                 # i dont know - bad line?  ignore.
1647                 print STDERR "Warning(${file}:$.): bad line: $_";
1648                 ++$warnings;
1649             }
1650         } elsif ($state == 3) { # scanning for function { (end of prototype)
1651             if ($decl_type eq 'function') {
1652                 process_state3_function($_, $file);
1653             } else {
1654                 process_state3_type($_, $file);
1655             }
1656         } elsif ($state == 4) {
1657                 # Documentation block
1658                 if (/$doc_block/) {
1659                         dump_section($section, $contents);
1660                         output_intro({'sectionlist' => \@sectionlist,
1661                                       'sections' => \%sections });
1662                         $contents = "";
1663                         $function = "";
1664                         %constants = ();
1665                         %parameterdescs = ();
1666                         %parametertypes = ();
1667                         @parameterlist = ();
1668                         %sections = ();
1669                         @sectionlist = ();
1670                         $prototype = "";
1671                         if ( $1 eq "" ) {
1672                                 $section = $section_intro;
1673                         } else {
1674                                 $section = $1;
1675                         }
1676                 }
1677                 elsif (/$doc_end/)
1678                 {
1679                         dump_section($section, $contents);
1680                         output_intro({'sectionlist' => \@sectionlist,
1681                                       'sections' => \%sections });
1682                         $contents = "";
1683                         $function = "";
1684                         %constants = ();
1685                         %parameterdescs = ();
1686                         %parametertypes = ();
1687                         @parameterlist = ();
1688                         %sections = ();
1689                         @sectionlist = ();
1690                         $prototype = "";
1691                         $state = 0;
1692                 }
1693                 elsif (/$doc_content/)
1694                 {
1695                         if ( $1 eq "" )
1696                         {
1697                                 $contents .= $blankline;
1698                         }
1699                         else
1700                         {
1701                                 $contents .= $1 . "\n";
1702                         }
1703                 }
1704           }
1705     }
1706     if ($initial_section_counter == $section_counter) {
1707         print STDERR "Warning(${file}): no structured comments found\n";
1708         if ($output_mode eq "sgml") {
1709             # The template wants at least one RefEntry here; make one.
1710             print "<refentry>\n";
1711             print " <refnamediv>\n";
1712             print "  <refname>\n";
1713             print "   ${file}\n";
1714             print "  </refname>\n";
1715             print "  <refpurpose>\n";
1716             print "   Document generation inconsistency\n";
1717             print "  </refpurpose>\n";
1718             print " </refnamediv>\n";
1719             print " <refsect1>\n";
1720             print "  <title>\n";
1721             print "   Oops\n";
1722             print "  </title>\n";
1723             print "  <warning>\n";
1724             print "   <para>\n";
1725             print "    The template for this document tried to insert\n";
1726             print "    the structured comment from the file\n";
1727             print "    <filename>${file}</filename> at this point,\n";
1728             print "    but none was found.\n";
1729             print "    This dummy section is inserted to allow\n";
1730             print "    generation to continue.\n";
1731             print "   </para>\n";
1732             print "  </warning>\n";
1733             print " </refsect1>\n";
1734             print "</refentry>\n";
1735         }
1736     }
1737 }