scripts/kernel-doc

   1 #!/usr/bin/perl
   2
   3 ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved        ##
   4 ## Copyright (C) 2000  Tim Waugh <twaugh@redhat.com>             ##
   5 ##                                                               ##
   6 ## This software falls under the GNU General Public License.     ##
   7 ## Please read the COPYING file for more information             ##
   8
   9 #
  10 # This will read a 'c' file and scan for embedded comments in the
  11 # style of gnome comments (+minor extensions - see below).
  12 #
  13
  14 # Note: This only supports 'c'.
  15
  16 # usage:
  17 # kerneldoc [ -docbook | -html | -text | -man ]
  18 #           [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
  19 # or
  20 #           [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile
  21 #
  22 #  Set output format using one of -docbook -html -text or -man.  Default is man.
  23 #
  24 #  -function funcname
  25 #       If set, then only generate documentation for the given function(s).  All
  26 #       other functions are ignored.
  27 #
  28 #  -nofunction funcname
  29 #       If set, then only generate documentation for the other function(s).  All
  30 #       other functions are ignored. Cannot be used with -function together
  31 #       (yes thats a bug - perl hackers can fix it 8))
  32 #
  33 #  c files - list of 'c' files to process
  34 #
  35 #  All output goes to stdout, with errors to stderr.
  36
  37 #
  38 # format of comments.
  39 # In the following table, (...)? signifies optional structure.
  40 #                         (...)* signifies 0 or more structure elements
  41 # /**
  42 #  * function_name(:)? (- short description)?
  43 # (* @parameterx: (description of parameter x)?)*
  44 # (* a blank line)?
  45 #  * (Description:)? (Description of function)?
  46 #  * (section header: (section description)? )*
  47 #  (*)?*/
  48 #
  49 # So .. the trivial example would be:
  50 #
  51 # /**
  52 #  * my_function
  53 #  **/
  54 #
  55 # If the Description: header tag is ommitted, then there must be a blank line
  56 # after the last parameter specification.
  57 # e.g.
  58 # /**
  59 #  * my_function - does my stuff
  60 #  * @my_arg: its mine damnit
  61 #  *
  62 #  * Does my stuff explained.
  63 #  */
  64 #
  65 #  or, could also use:
  66 # /**
  67 #  * my_function - does my stuff
  68 #  * @my_arg: its mine damnit
  69 #  * Description: Does my stuff explained.
  70 #  */
  71 # etc.
  72 #
  73 # All descriptions can be multiline, apart from the short function description.
  74 #
  75 # All descriptive text is further processed, scanning for the following special
  76 # patterns, which are highlighted appropriately.
  77 #
  78 # 'funcname()' - function
  79 # '$ENVVAR' - environmental variable
  80 # '&struct_name' - name of a structure (up to two words including 'struct')
  81 # '@parameter' - name of a parameter
  82 # '%CONST' - name of a constant.
  83
  84 # match expressions used to find embedded type information
  85 $type_constant = "\\\%([-_\\w]+)";
  86 $type_func = "(\\w+)\\(\\)";
  87 $type_param = "\\\@(\\w+)";
  88 $type_struct = "\\\&((struct\\s*)?[_\\w]+)";
  89 $type_env = "(\\\$\\w+)";
  90
  91
  92 # Output conversion substitutions.
  93 #  One for each output format
  94
  95 # these work fairly well
  96 %highlights_html = ( $type_constant, "<i>\$1</i>",
  97                      $type_func, "<b>\$1</b>",
  98                      $type_struct, "<i>\$1</i>",
  99                      $type_param, "<tt><b>\$1</b></tt>" );
 100 $blankline_html = "<p>";
 101
 102 # sgml, docbook format
 103 %highlights_sgml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
 104                      $type_constant, "<constant>\$1</constant>",
 105                      $type_func, "<function>\$1</function>",
 106                      $type_struct, "<structname>\$1</structname>",
 107                      $type_env, "<envar>\$1</envar>",
 108                      $type_param, "<parameter>\$1</parameter>" );
 109 $blankline_sgml = "</para><para>\n";
 110
 111 # gnome, docbook format
 112 %highlights_gnome = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",
 113                      $type_func, "<function>\$1</function>",
 114                      $type_struct, "<structname>\$1</structname>",
 115                      $type_env, "<envar>\$1</envar>",
 116                      $type_param, "<parameter>\$1</parameter>" );
 117 $blankline_gnome = "</para><para>\n";
 118
 119 # these are pretty rough
 120 %highlights_man = ( $type_constant, "\$1",
 121                     $type_func, "\\\\fB\$1\\\\fP",
 122                     $type_struct, "\\\\fI\$1\\\\fP",
 123                     $type_param, "\\\\fI\$1\\\\fP" );
 124 $blankline_man = "";
 125
 126 # text-mode
 127 %highlights_text = ( $type_constant, "\$1",
 128                      $type_func, "\$1",
 129                      $type_struct, "\$1",
 130                      $type_param, "\$1" );
 131 $blankline_text = "";
 132
 133
 134 sub usage {
 135     print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ]\n";
 136     print "         [ -function funcname [ -function funcname ...] ]\n";
 137     print "         [ -nofunction funcname [ -nofunction funcname ...] ]\n";
 138     print "         c source file(s) > outputfile\n";
 139     exit 1;
 140 }
 141
 142 # read arguments
 143 if ($#ARGV==-1) {
 144     usage();
 145 }
 146
 147 $verbose = 0;
 148 $output_mode = "man";
 149 %highlights = %highlights_man;
 150 $blankline = $blankline_man;
 151 $modulename = "API Documentation";
 152 $function_only = 0;
 153 while ($ARGV[0] =~ m/^-(.*)/) {
 154     $cmd = shift @ARGV;
 155     if ($cmd eq "-html") {
 156         $output_mode = "html";
 157         %highlights = %highlights_html;
 158         $blankline = $blankline_html;
 159     } elsif ($cmd eq "-man") {
 160         $output_mode = "man";
 161         %highlights = %highlights_man;
 162         $blankline = $blankline_man;
 163     } elsif ($cmd eq "-text") {
 164         $output_mode = "text";
 165         %highlights = %highlights_text;
 166         $blankline = $blankline_text;
 167     } elsif ($cmd eq "-docbook") {
 168         $output_mode = "sgml";
 169         %highlights = %highlights_sgml;
 170         $blankline = $blankline_sgml;
 171     } elsif ($cmd eq "-gnome") {
 172         $output_mode = "gnome";
 173         %highlights = %highlights_gnome;
 174         $blankline = $blankline_gnome;
 175     } elsif ($cmd eq "-module") { # not needed for sgml, inherits from calling document
 176         $modulename = shift @ARGV;
 177     } elsif ($cmd eq "-function") { # to only output specific functions
 178         $function_only = 1;
 179         $function = shift @ARGV;
 180         $function_table{$function} = 1;
 181     } elsif ($cmd eq "-nofunction") { # to only output specific functions
 182         $function_only = 2;
 183         $function = shift @ARGV;
 184         $function_table{$function} = 1;
 185     } elsif ($cmd eq "-v") {
 186         $verbose = 1;
 187     } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
 188         usage();
 189     }
 190 }
 191
 192
 193 # generate a sequence of code that will splice in highlighting information
 194 # using the s// operator.
 195 $dohighlight = "";
 196 foreach $pattern (keys %highlights) {
 197 #    print "scanning pattern $pattern ($highlights{$pattern})\n";
 198     $dohighlight .=  "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
 199 }
 200
 201 ##
 202 # dumps section contents to arrays/hashes intended for that purpose.
 203 #
 204 sub dump_section {
 205     my $name = shift @_;
 206     my $contents = join "\n", @_;
 207
 208     if ($name =~ m/$type_constant/) {
 209         $name = $1;
 210 #       print STDERR "constant section '$1' = '$contents'\n";
 211         $constants{$name} = $contents;
 212     } elsif ($name =~ m/$type_param/) {
 213 #       print STDERR "parameter def '$1' = '$contents'\n";
 214         $name = $1;
 215         $parameters{$name} = $contents;
 216     } else {
 217 #       print STDERR "other section '$name' = '$contents'\n";
 218         $sections{$name} = $contents;
 219         push @sectionlist, $name;
 220     }
 221 }
 222
 223 ##
 224 # output function
 225 #
 226 # parameters, a hash.
 227 #  function => "function name"
 228 #  parameterlist => @list of parameters
 229 #  parameters => %parameter descriptions
 230 #  sectionlist => @list of sections
 231 #  sections => %descriont descriptions
 232 #
 233
 234 sub output_highlight {
 235     my $contents = join "\n", @_;
 236     my $line;
 237
 238     eval $dohighlight;
 239     foreach $line (split "\n", $contents) {
 240         if ($line eq ""){
 241             print $lineprefix, $blankline;
 242         } else {
 243             $line =~ s/\\\\\\/\&/g;
 244             print $lineprefix, $line;
 245         }
 246         print "\n";
 247     }
 248 }
 249
 250
 251 # output in html
 252 sub output_html {
 253     my %args = %{$_[0]};
 254     my ($parameter, $section);
 255     my $count;
 256     print "<h2>Function</h2>\n";
 257
 258     print "<i>".$args{'functiontype'}."</i>\n";
 259     print "<b>".$args{'function'}."</b>\n";
 260     print "(";
 261     $count = 0;
 262     foreach $parameter (@{$args{'parameterlist'}}) {
 263         $type = $args{'parametertypes'}{$parameter};
 264         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 265             # pointer-to-function
 266             print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
 267         } else {
 268             print "<i>".$type."</i> <b>".$parameter."</b>";
 269         }
 270         if ($count != $#{$args{'parameterlist'}}) {
 271             $count++;
 272             print ",\n";
 273         }
 274     }
 275     print ")\n";
 276
 277     print "<h3>Arguments</h3>\n";
 278     print "<dl>\n";
 279     foreach $parameter (@{$args{'parameterlist'}}) {
 280         print "<dt><b>".$parameter."</b>\n";
 281         print "<dd>";
 282         output_highlight($args{'parameters'}{$parameter});
 283     }
 284     print "</dl>\n";
 285     foreach $section (@{$args{'sectionlist'}}) {
 286         print "<h3>$section</h3>\n";
 287         print "<blockquote>\n";
 288         output_highlight($args{'sections'}{$section});
 289         print "</blockquote>\n";
 290     }
 291     print "<hr>\n";
 292 }
 293
 294
 295 # output in html
 296 sub output_intro_html {
 297     my %args = %{$_[0]};
 298     my ($parameter, $section);
 299     my $count;
 300
 301     foreach $section (@{$args{'sectionlist'}}) {
 302         print "<h3>$section</h3>\n";
 303         print "<ul>\n";
 304         output_highlight($args{'sections'}{$section});
 305         print "</ul>\n";
 306     }
 307     print "<hr>\n";
 308 }
 309
 310
 311
 312 # output in sgml DocBook
 313 sub output_sgml {
 314     my %args = %{$_[0]};
 315     my ($parameter, $section);
 316     my $count;
 317     my $id;
 318
 319     $id = "API-".$args{'function'};
 320     $id =~ s/[^A-Za-z0-9]/-/g;
 321
 322     print "<refentry>\n";
 323     print "<refmeta>\n";
 324     print "<refentrytitle><phrase id=\"$id\">".$args{'function'}."</phrase></refentrytitle>\n";
 325     print "</refmeta>\n";
 326     print "<refnamediv>\n";
 327     print " <refname>".$args{'function'}."</refname>\n";
 328     print " <refpurpose>\n";
 329     print "  ";
 330     output_highlight ($args{'purpose'});
 331     print " </refpurpose>\n";
 332     print "</refnamediv>\n";
 333
 334     print "<refsynopsisdiv>\n";
 335     print " <title>Synopsis</title>\n";
 336     print "  <funcsynopsis>\n";
 337     print "   <funcdef>".$args{'functiontype'}." ";
 338     print "<function>".$args{'function'}." ";
 339     print "</function></funcdef>\n";
 340
 341 #    print "<refsect1>\n";
 342 #    print " <title>Synopsis</title>\n";
 343 #    print "  <funcsynopsis>\n";
 344 #    print "   <funcdef>".$args{'functiontype'}." ";
 345 #    print "<function>".$args{'function'}." ";
 346 #    print "</function></funcdef>\n";
 347
 348     $count = 0;
 349     if ($#{$args{'parameterlist'}} >= 0) {
 350         foreach $parameter (@{$args{'parameterlist'}}) {
 351             $type = $args{'parametertypes'}{$parameter};
 352             if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 353                 # pointer-to-function
 354                 print "   <paramdef>$1<parameter>$parameter</parameter>)\n";
 355                 print "     <funcparams>$2</funcparams></paramdef>\n";
 356             } else {
 357                 print "   <paramdef>".$type;
 358                 print " <parameter>$parameter</parameter></paramdef>\n";
 359             }
 360         }
 361     } else {
 362         print "  <void>\n";
 363     }
 364     print "  </funcsynopsis>\n";
 365     print "</refsynopsisdiv>\n";
 366 #    print "</refsect1>\n";
 367
 368     # print parameters
 369     print "<refsect1>\n <title>Arguments</title>\n";
 370 #    print "<para>\nArguments\n";
 371     if ($#{$args{'parameterlist'}} >= 0) {
 372         print " <variablelist>\n";
 373         foreach $parameter (@{$args{'parameterlist'}}) {
 374             print "  <varlistentry>\n   <term><parameter>$parameter</parameter></term>\n";
 375             print "   <listitem>\n    <para>\n";
 376             $lineprefix="     ";
 377             output_highlight($args{'parameters'}{$parameter});
 378             print "    </para>\n   </listitem>\n  </varlistentry>\n";
 379         }
 380         print " </variablelist>\n";
 381     } else {
 382         print " <para>\n  None\n </para>\n";
 383     }
 384     print "</refsect1>\n";
 385
 386     # print out each section
 387     $lineprefix="   ";
 388     foreach $section (@{$args{'sectionlist'}}) {
 389         print "<refsect1>\n <title>$section</title>\n <para>\n";
 390 #       print "<para>\n$section\n";
 391         if ($section =~ m/EXAMPLE/i) {
 392             print "<example><para>\n";
 393         }
 394         output_highlight($args{'sections'}{$section});
 395 #       print "</para>";
 396         if ($section =~ m/EXAMPLE/i) {
 397             print "</para></example>\n";
 398         }
 399         print " </para>\n</refsect1>\n";
 400     }
 401
 402     print "</refentry>\n\n";
 403 }
 404
 405 # output in sgml DocBook
 406 sub output_intro_sgml {
 407     my %args = %{$_[0]};
 408     my ($parameter, $section);
 409     my $count;
 410     my $id;
 411
 412     $id = $args{'module'};
 413     $id =~ s/[^A-Za-z0-9]/-/g;
 414
 415     # print out each section
 416     $lineprefix="   ";
 417     foreach $section (@{$args{'sectionlist'}}) {
 418         print "<refsect1>\n <title>$section</title>\n <para>\n";
 419 #       print "<para>\n$section\n";
 420         if ($section =~ m/EXAMPLE/i) {
 421             print "<example><para>\n";
 422         }
 423         output_highlight($args{'sections'}{$section});
 424 #       print "</para>";
 425         if ($section =~ m/EXAMPLE/i) {
 426             print "</para></example>\n";
 427         }
 428         print " </para>\n</refsect1>\n";
 429     }
 430
 431     print "\n\n";
 432 }
 433
 434 # output in sgml DocBook
 435 sub output_gnome {
 436     my %args = %{$_[0]};
 437     my ($parameter, $section);
 438     my $count;
 439     my $id;
 440
 441     $id = $args{'module'}."-".$args{'function'};
 442     $id =~ s/[^A-Za-z0-9]/-/g;
 443
 444     print "<sect2>\n";
 445     print " <title id=\"$id\">".$args{'function'}."</title>\n";
 446
 447 #    print "<simplesect>\n";
 448 #    print " <title>Synopsis</title>\n";
 449     print "  <funcsynopsis>\n";
 450     print "   <funcdef>".$args{'functiontype'}." ";
 451     print "<function>".$args{'function'}." ";
 452     print "</function></funcdef>\n";
 453
 454     $count = 0;
 455     if ($#{$args{'parameterlist'}} >= 0) {
 456         foreach $parameter (@{$args{'parameterlist'}}) {
 457             $type = $args{'parametertypes'}{$parameter};
 458             if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 459                 # pointer-to-function
 460                 print "   <paramdef>$1 <parameter>$parameter</parameter>)\n";
 461                 print "     <funcparams>$2</funcparams></paramdef>\n";
 462             } else {
 463                 print "   <paramdef>".$type;
 464                 print " <parameter>$parameter</parameter></paramdef>\n";
 465             }
 466         }
 467     } else {
 468         print "  <void>\n";
 469     }
 470     print "  </funcsynopsis>\n";
 471 #    print "</simplesect>\n";
 472 #    print "</refsect1>\n";
 473
 474     # print parameters
 475 #    print "<simplesect>\n <title>Arguments</title>\n";
 476 #    if ($#{$args{'parameterlist'}} >= 0) {
 477 #       print " <variablelist>\n";
 478 #       foreach $parameter (@{$args{'parameterlist'}}) {
 479 #           print "  <varlistentry>\n   <term><parameter>$parameter</parameter></term>\n";
 480 #           print "   <listitem>\n    <para>\n";
 481 #           $lineprefix="     ";
 482 #           output_highlight($args{'parameters'}{$parameter});
 483 #           print "    </para>\n   </listitem>\n  </varlistentry>\n";
 484 #       }
 485 #       print " </variablelist>\n";
 486 #    } else {
 487 #       print " <para>\n  None\n </para>\n";
 488 #    }
 489 #    print "</simplesect>\n";
 490
 491 #    print "<simplesect>\n <title>Arguments</title>\n";
 492     if ($#{$args{'parameterlist'}} >= 0) {
 493         print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
 494         print "<tgroup cols=\"2\">\n";
 495         print "<colspec colwidth=\"2*\">\n";
 496         print "<colspec colwidth=\"8*\">\n";
 497         print "<tbody>\n";
 498         foreach $parameter (@{$args{'parameterlist'}}) {
 499             print "  <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
 500             print "   <entry>\n";
 501             $lineprefix="     ";
 502             output_highlight($args{'parameters'}{$parameter});
 503             print "    </entry></row>\n";
 504         }
 505         print " </tbody></tgroup></informaltable>\n";
 506     } else {
 507         print " <para>\n  None\n </para>\n";
 508     }
 509 #    print "</simplesect>\n";
 510
 511     # print out each section
 512     $lineprefix="   ";
 513     foreach $section (@{$args{'sectionlist'}}) {
 514         print "<simplesect>\n <title>$section</title>\n";
 515 #       print "<para>\n$section\n";
 516         if ($section =~ m/EXAMPLE/i) {
 517             print "<example><programlisting>\n";
 518         } else {
 519         }
 520         print "<para>\n";
 521         output_highlight($args{'sections'}{$section});
 522 #       print "</para>";
 523         print "</para>\n";
 524         if ($section =~ m/EXAMPLE/i) {
 525             print "</programlisting></example>\n";
 526         } else {
 527         }
 528         print " </simplesect>\n";
 529     }
 530
 531     print "</sect2>\n\n";
 532 }
 533
 534 ##
 535 # output in man
 536 sub output_man {
 537     my %args = %{$_[0]};
 538     my ($parameter, $section);
 539     my $count;
 540
 541     print ".TH \"$args{'module'}\" 4 \"$args{'function'}\" \"25 May 1998\" \"API Manual\" LINUX\n";
 542
 543     print ".SH NAME\n";
 544     print $args{'function'}." \\- ".$args{'purpose'}."\n";
 545
 546     print ".SH SYNOPSIS\n";
 547     print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n";
 548     $count = 0;
 549     $parenth = "(";
 550     $post = ",";
 551     foreach $parameter (@{$args{'parameterlist'}}) {
 552         if ($count == $#{$args{'parameterlist'}}) {
 553             $post = ");";
 554         }
 555         $type = $args{'parametertypes'}{$parameter};
 556         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 557             # pointer-to-function
 558             print ".BI \"".$parenth.$1."\" ".$parameter." \") (".$2.")".$post."\"\n";
 559         } else {
 560             $type =~ s/([^\*])$/\1 /;
 561             print ".BI \"".$parenth.$type."\" ".$parameter." \"".$post."\"\n";
 562         }
 563         $count++;
 564         $parenth = "";
 565     }
 566
 567     print ".SH Arguments\n";
 568     foreach $parameter (@{$args{'parameterlist'}}) {
 569         print ".IP \"".$parameter."\" 12\n";
 570         output_highlight($args{'parameters'}{$parameter});
 571     }
 572     foreach $section (@{$args{'sectionlist'}}) {
 573         print ".SH \"$section\"\n";
 574         output_highlight($args{'sections'}{$section});
 575     }
 576 }
 577
 578 sub output_intro_man {
 579     my %args = %{$_[0]};
 580     my ($parameter, $section);
 581     my $count;
 582
 583     print ".TH \"$args{'module'}\" 4 \"$args{'module'}\" \"25 May 1998\" \"API Manual\" LINUX\n";
 584
 585     foreach $section (@{$args{'sectionlist'}}) {
 586         print ".SH \"$section\"\n";
 587         output_highlight($args{'sections'}{$section});
 588     }
 589 }
 590
 591 ##
 592 # output in text
 593 sub output_text {
 594     my %args = %{$_[0]};
 595     my ($parameter, $section);
 596
 597     print "Function:\n\n";
 598     $start=$args{'functiontype'}." ".$args{'function'}." (";
 599     print $start;
 600     $count = 0;
 601     foreach $parameter (@{$args{'parameterlist'}}) {
 602         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 603             # pointer-to-function
 604             print $1.$parameter.") (".$2;
 605         } else {
 606             print $type." ".$parameter;
 607         }
 608         if ($count != $#{$args{'parameterlist'}}) {
 609             $count++;
 610             print ",\n";
 611             print " " x length($start);
 612         } else {
 613             print ");\n\n";
 614         }
 615     }
 616
 617     print "Arguments:\n\n";
 618     foreach $parameter (@{$args{'parameterlist'}}) {
 619         print $parameter."\n\t".$args{'parameters'}{$parameter}."\n";
 620     }
 621     foreach $section (@{$args{'sectionlist'}}) {
 622         print "$section:\n\n";
 623         output_highlight($args{'sections'}{$section});
 624     }
 625     print "\n\n";
 626 }
 627
 628 sub output_intro_text {
 629     my %args = %{$_[0]};
 630     my ($parameter, $section);
 631
 632     foreach $section (@{$args{'sectionlist'}}) {
 633         print " $section:\n";
 634         print "    -> ";
 635         output_highlight($args{'sections'}{$section});
 636     }
 637 }
 638
 639 ##
 640 # generic output function - calls the right one based
 641 # on current output mode.
 642 sub output_function {
 643 #    output_html(@_);
 644     eval "output_".$output_mode."(\@_);";
 645 }
 646
 647 ##
 648 # generic output function - calls the right one based
 649 # on current output mode.
 650 sub output_intro {
 651 #    output_html(@_);
 652     eval "output_intro_".$output_mode."(\@_);";
 653 }
 654
 655
 656 ##
 657 # takes a function prototype and spits out all the details
 658 # stored in the global arrays/hsahes.
 659 sub dump_function {
 660     my $prototype = shift @_;
 661
 662     $prototype =~ s/^static+ //;
 663     $prototype =~ s/^extern+ //;
 664     $prototype =~ s/^inline+ //;
 665     $prototype =~ s/^__inline__+ //;
 666
 667     if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 668         $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 669         $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 670         $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 671         $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/)  {
 672         $return_type = $1;
 673         $function_name = $2;
 674         $args = $3;
 675
 676         # allow for up to fours args to function pointers
 677         $args =~ s/(\([^\),]+),/\1#/g;
 678         $args =~ s/(\([^\),]+),/\1#/g;
 679         $args =~ s/(\([^\),]+),/\1#/g;
 680 #       print STDERR "ARGS = '$args'\n";
 681
 682         foreach $arg (split ',', $args) {
 683             # strip leading/trailing spaces
 684             $arg =~ s/^\s*//;
 685             $arg =~ s/\s*$//;
 686
 687             if ($arg =~ m/\(/) {
 688                 # pointer-to-function
 689                 $arg =~ tr/#/,/;
 690                 $arg =~ m/[^\(]+\(\*([^\)]+)\)/;
 691                 $param = $1;
 692                 $type = $arg;
 693                 $type =~ s/([^\(]+\(\*)$param/\1/;
 694             } else {
 695                 # evil magic to get fixed array parameters to work
 696                 $arg =~ s/(.+\s+)(.+)\[.*/\1* \2/;
 697 #               print STDERR "SCAN ARG: '$arg'\n";
 698                 @args = split('\s', $arg);
 699
 700 #               print STDERR " -> @args\n";
 701                 $param = pop @args;
 702 #               print STDERR " -> @args\n";
 703                 if ($param =~ m/^(\*+)(.*)/) {
 704                     $param = $2;
 705                     push @args, $1;
 706                 }
 707                 $type = join " ", @args;
 708             }
 709
 710             if ($type eq "" && $param eq "...")
 711             {
 712                 $type="...";
 713                 $param="...";
 714                 $parameters{"..."} = "variable arguments";
 715             }
 716             if ($type eq "")
 717             {
 718                 $type="";
 719                 $param="void";
 720                 $parameters{void} = "no arguments";
 721             }
 722             if ($parameters{$param} eq "") {
 723                 $parameters{$param} = "-- undescribed --";
 724                 print STDERR "Warning($file:$lineno): Function parameter '$param' not described in '$function_name'\n";
 725             }
 726
 727             push @parameterlist, $param;
 728             $parametertypes{$param} = $type;
 729 #           print STDERR "param = '$param', type = '$type'\n";
 730         }
 731     } else {
 732         print STDERR "Error($lineno): cannot understand prototype: '$prototype'\n";
 733         return;
 734     }
 735
 736     if ($function_only==0 ||
 737      ( $function_only == 1 && defined($function_table{$function_name})) ||
 738      ( $function_only == 2 && !defined($function_table{$function_name})))
 739     {
 740         output_function({'function' => $function_name,
 741                          'module' => $modulename,
 742                          'functiontype' => $return_type,
 743                          'parameterlist' => \@parameterlist,
 744                          'parameters' => \%parameters,
 745                          'parametertypes' => \%parametertypes,
 746                          'sectionlist' => \@sectionlist,
 747                          'sections' => \%sections,
 748                          'purpose' => $function_purpose
 749                          });
 750     }
 751 }
 752
 753 ######################################################################
 754 # main
 755 # states
 756 # 0 - normal code
 757 # 1 - looking for function name
 758 # 2 - scanning field start.
 759 # 3 - scanning prototype.
 760 $state = 0;
 761 $section = "";
 762
 763 $doc_special = "\@\%\$\&";
 764
 765 $doc_start = "^/\\*\\*\$";
 766 $doc_end = "\\*/";
 767 $doc_com = "\\s*\\*\\s*";
 768 $doc_func = $doc_com."(\\w+):?";
 769 $doc_sect = $doc_com."([".$doc_special."]?[\\w ]+):(.*)";
 770 $doc_content = $doc_com."(.*)";
 771 $doc_block = $doc_com."DOC:\\s*(.*)?";
 772
 773 %constants = ();
 774 %parameters = ();
 775 @parameterlist = ();
 776 %sections = ();
 777 @sectionlist = ();
 778
 779 $contents = "";
 780 $section_default = "Description";       # default section
 781 $section_intro = "Introduction";
 782 $section = $section_default;
 783
 784 $lineno = 0;
 785 foreach $file (@ARGV) {
 786     chomp($file);
 787     if (!open(IN,"<$file")) {
 788         print STDERR "Error: Cannot open file $file\n";
 789         next;
 790     }
 791     while (<IN>) {
 792         $lineno++;
 793
 794         if ($state == 0) {
 795             if (/$doc_start/o) {
 796                 $state = 1;             # next line is always the function name
 797             }
 798         } elsif ($state == 1) { # this line is the function name (always)
 799             if (/$doc_block/o) {
 800                 $state = 4;
 801                 $contents = "";
 802                 if ( $1 eq "" ) {
 803                         $section = $section_intro;
 804                 } else {
 805                         $section = $1;
 806                 }
 807             }
 808             elsif (/$doc_func/o) {
 809                 $function = $1;
 810                 $state = 2;
 811                 if (/-(.*)/) {
 812                     $function_purpose = $1;
 813                 } else {
 814                     $function_purpose = "";
 815                 }
 816                 if ($verbose) {
 817                     print STDERR "Info($lineno): Scanning doc for $function\n";
 818                 }
 819             } else {
 820                 print STDERR "WARN($lineno): Cannot understand $_ on line $lineno",
 821                 " - I thought it was a doc line\n";
 822                 $state = 0;
 823             }
 824         } elsif ($state == 2) { # look for head: lines, and include content
 825             if (/$doc_sect/o) {
 826                 $newsection = $1;
 827                 $newcontents = $2;
 828
 829                 if ($contents ne "") {
 830                     $contents =~ s/\&/\\\\\\amp;/g;
 831                     $contents =~ s/\</\\\\\\lt;/g;
 832                     $contents =~ s/\>/\\\\\\gt;/g;
 833                     dump_section($section, $contents);
 834                     $section = $section_default;
 835                 }
 836
 837                 $contents = $newcontents;
 838                 if ($contents ne "") {
 839                     $contents .= "\n";
 840                 }
 841                 $section = $newsection;
 842             } elsif (/$doc_end/) {
 843
 844                 if ($contents ne "") {
 845                     $contents =~ s/\&/\\\\\\amp;/g;
 846                     $contents =~ s/\</\\\\\\lt;/g;
 847                     $contents =~ s/\>/\\\\\\gt;/g;
 848                     dump_section($section, $contents);
 849                     $section = $section_default;
 850                     $contents = "";
 851                 }
 852
 853 #           print STDERR "end of doc comment, looking for prototype\n";
 854                 $prototype = "";
 855                 $state = 3;
 856             } elsif (/$doc_content/) {
 857                 # miguel-style comment kludge, look for blank lines after
 858                 # @parameter line to signify start of description
 859                 if ($1 eq "" && $section =~ m/^@/) {
 860                     $contents =~ s/\&/\\\\\\amp;/g;
 861                     $contents =~ s/\</\\\\\\lt;/g;
 862                     $contents =~ s/\>/\\\\\\gt;/g;
 863                     dump_section($section, $contents);
 864                     $section = $section_default;
 865                     $contents = "";
 866                 } else {
 867                     $contents .= $1."\n";
 868                 }
 869             } else {
 870                 # i dont know - bad line?  ignore.
 871                 print STDERR "WARNING($lineno): bad line: $_";
 872             }
 873         } elsif ($state == 3) { # scanning for function { (end of prototype)
 874             if (m#\s*/\*\s+MACDOC\s*#io) {
 875               # do nothing
 876             }
 877             elsif (/([^\{]*)/) {
 878                 $prototype .= $1;
 879             }
 880             if (/\{/) {
 881                 $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
 882                 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
 883                 $prototype =~ s@^ +@@gos; # strip leading spaces
 884                 dump_function($prototype);
 885
 886                 $function = "";
 887                 %constants = ();
 888                 %parameters = ();
 889                 %parametertypes = ();
 890                 @parameterlist = ();
 891                 %sections = ();
 892                 @sectionlist = ();
 893                 $prototype = "";
 894
 895                 $state = 0;
 896             }
 897         } elsif ($state == 4) {
 898                 # Documentation block
 899                 if (/$doc_block/) {
 900                         dump_section($section, $contents);
 901                         output_intro({'sectionlist' => \@sectionlist,
 902                                       'sections' => \%sections });
 903                         $contents = "";
 904                         $function = "";
 905                         %constants = ();
 906                         %parameters = ();
 907                         %parametertypes = ();
 908                         @parameterlist = ();
 909                         %sections = ();
 910                         @sectionlist = ();
 911                         $prototype = "";
 912                         if ( $1 eq "" ) {
 913                                 $section = $section_intro;
 914                         } else {
 915                                 $section = $1;
 916                         }
 917                 }
 918                 elsif (/$doc_end/)
 919                 {
 920                         dump_section($section, $contents);
 921                         output_intro({'sectionlist' => \@sectionlist,
 922                                       'sections' => \%sections });
 923                         $contents = "";
 924                         $function = "";
 925                         %constants = ();
 926                         %parameters = ();
 927                         %parametertypes = ();
 928                         @parameterlist = ();
 929                         %sections = ();
 930                         @sectionlist = ();
 931                         $prototype = "";
 932                         $state = 0;
 933                 }
 934                 elsif (/$doc_content/)
 935                 {
 936                         if ( $1 eq "" )
 937                         {
 938                                 $contents .= $blankline;
 939                         }
 940                         else
 941                         {
 942                                 $contents .= $1 . "\n";
 943                         }
 944                 }
 945           }
 946     }
 947 }
 948