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