utils/docs/libfaim-doc.pl

   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 = "libfaim 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 "  ".$args{'purpose'}."\n";
 330     print " </refpurpose>\n";
 331     print "</refnamediv>\n";
 332
 333     print "<refsynopsisdiv>\n";
 334     print " <title>Synopsis</title>\n";
 335     print "  <funcsynopsis>\n";
 336     print "   <funcdef>".$args{'functiontype'}." ";
 337     print "<function>".$args{'function'}." ";
 338     print "</function></funcdef>\n";
 339
 340 #    print "<refsect1>\n";
 341 #    print " <title>Synopsis</title>\n";
 342 #    print "  <funcsynopsis>\n";
 343 #    print "   <funcdef>".$args{'functiontype'}." ";
 344 #    print "<function>".$args{'function'}." ";
 345 #    print "</function></funcdef>\n";
 346
 347     $count = 0;
 348     if ($#{$args{'parameterlist'}} >= 0) {
 349         foreach $parameter (@{$args{'parameterlist'}}) {
 350             $type = $args{'parametertypes'}{$parameter};
 351             if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 352                 # pointer-to-function
 353                 print "   <paramdef>$1<parameter>$parameter</parameter>)\n";
 354                 print "     <funcparams>$2</funcparams></paramdef>\n";
 355             } else {
 356                 print "   <paramdef>".$type;
 357                 print " <parameter>$parameter</parameter></paramdef>\n";
 358             }
 359         }
 360     } else {
 361         print "  <void>\n";
 362     }
 363     print "  </funcsynopsis>\n";
 364     print "</refsynopsisdiv>\n";
 365 #    print "</refsect1>\n";
 366
 367     # print parameters
 368     print "<refsect1>\n <title>Arguments</title>\n";
 369 #    print "<para>\nArguments\n";
 370     if ($#{$args{'parameterlist'}} >= 0) {
 371         print " <variablelist>\n";
 372         foreach $parameter (@{$args{'parameterlist'}}) {
 373             print "  <varlistentry>\n   <term><parameter>$parameter</parameter></term>\n";
 374             print "   <listitem>\n    <para>\n";
 375             $lineprefix="     ";
 376             output_highlight($args{'parameters'}{$parameter});
 377             print "    </para>\n   </listitem>\n  </varlistentry>\n";
 378         }
 379         print " </variablelist>\n";
 380     } else {
 381         print " <para>\n  None\n </para>\n";
 382     }
 383     print "</refsect1>\n";
 384
 385     # print out each section
 386     $lineprefix="   ";
 387     foreach $section (@{$args{'sectionlist'}}) {
 388         print "<refsect1>\n <title>$section</title>\n <para>\n";
 389 #       print "<para>\n$section\n";
 390         if ($section =~ m/EXAMPLE/i) {
 391             print "<example><para>\n";
 392         }
 393         output_highlight($args{'sections'}{$section});
 394 #       print "</para>";
 395         if ($section =~ m/EXAMPLE/i) {
 396             print "</para></example>\n";
 397         }
 398         print " </para>\n</refsect1>\n";
 399     }
 400
 401     print "</refentry>\n\n";
 402 }
 403
 404 # output in sgml DocBook
 405 sub output_intro_sgml {
 406     my %args = %{$_[0]};
 407     my ($parameter, $section);
 408     my $count;
 409     my $id;
 410
 411     $id = $args{'module'};
 412     $id =~ s/[^A-Za-z0-9]/-/g;
 413
 414     # print out each section
 415     $lineprefix="   ";
 416     foreach $section (@{$args{'sectionlist'}}) {
 417         print "<refsect1>\n <title>$section</title>\n <para>\n";
 418 #       print "<para>\n$section\n";
 419         if ($section =~ m/EXAMPLE/i) {
 420             print "<example><para>\n";
 421         }
 422         output_highlight($args{'sections'}{$section});
 423 #       print "</para>";
 424         if ($section =~ m/EXAMPLE/i) {
 425             print "</para></example>\n";
 426         }
 427         print " </para>\n</refsect1>\n";
 428     }
 429
 430     print "\n\n";
 431 }
 432
 433 # output in sgml DocBook
 434 sub output_gnome {
 435     my %args = %{$_[0]};
 436     my ($parameter, $section);
 437     my $count;
 438     my $id;
 439
 440     $id = $args{'module'}."-".$args{'function'};
 441     $id =~ s/[^A-Za-z0-9]/-/g;
 442
 443     print "<sect2>\n";
 444     print " <title id=\"$id\">".$args{'function'}."</title>\n";
 445
 446 #    print "<simplesect>\n";
 447 #    print " <title>Synopsis</title>\n";
 448     print "  <funcsynopsis>\n";
 449     print "   <funcdef>".$args{'functiontype'}." ";
 450     print "<function>".$args{'function'}." ";
 451     print "</function></funcdef>\n";
 452
 453     $count = 0;
 454     if ($#{$args{'parameterlist'}} >= 0) {
 455         foreach $parameter (@{$args{'parameterlist'}}) {
 456             $type = $args{'parametertypes'}{$parameter};
 457             if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 458                 # pointer-to-function
 459                 print "   <paramdef>$1 <parameter>$parameter</parameter>)\n";
 460                 print "     <funcparams>$2</funcparams></paramdef>\n";
 461             } else {
 462                 print "   <paramdef>".$type;
 463                 print " <parameter>$parameter</parameter></paramdef>\n";
 464             }
 465         }
 466     } else {
 467         print "  <void>\n";
 468     }
 469     print "  </funcsynopsis>\n";
 470 #    print "</simplesect>\n";
 471 #    print "</refsect1>\n";
 472
 473     # print parameters
 474 #    print "<simplesect>\n <title>Arguments</title>\n";
 475 #    if ($#{$args{'parameterlist'}} >= 0) {
 476 #       print " <variablelist>\n";
 477 #       foreach $parameter (@{$args{'parameterlist'}}) {
 478 #           print "  <varlistentry>\n   <term><parameter>$parameter</parameter></term>\n";
 479 #           print "   <listitem>\n    <para>\n";
 480 #           $lineprefix="     ";
 481 #           output_highlight($args{'parameters'}{$parameter});
 482 #           print "    </para>\n   </listitem>\n  </varlistentry>\n";
 483 #       }
 484 #       print " </variablelist>\n";
 485 #    } else {
 486 #       print " <para>\n  None\n </para>\n";
 487 #    }
 488 #    print "</simplesect>\n";
 489
 490 #    print "<simplesect>\n <title>Arguments</title>\n";
 491     if ($#{$args{'parameterlist'}} >= 0) {
 492         print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
 493         print "<tgroup cols=\"2\">\n";
 494         print "<colspec colwidth=\"2*\">\n";
 495         print "<colspec colwidth=\"8*\">\n";
 496         print "<tbody>\n";
 497         foreach $parameter (@{$args{'parameterlist'}}) {
 498             print "  <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
 499             print "   <entry>\n";
 500             $lineprefix="     ";
 501             output_highlight($args{'parameters'}{$parameter});
 502             print "    </entry></row>\n";
 503         }
 504         print " </tbody></tgroup></informaltable>\n";
 505     } else {
 506         print " <para>\n  None\n </para>\n";
 507     }
 508 #    print "</simplesect>\n";
 509
 510     # print out each section
 511     $lineprefix="   ";
 512     foreach $section (@{$args{'sectionlist'}}) {
 513         print "<simplesect>\n <title>$section</title>\n";
 514 #       print "<para>\n$section\n";
 515         if ($section =~ m/EXAMPLE/i) {
 516             print "<example><programlisting>\n";
 517         } else {
 518         }
 519         print "<para>\n";
 520         output_highlight($args{'sections'}{$section});
 521 #       print "</para>";
 522         print "</para>\n";
 523         if ($section =~ m/EXAMPLE/i) {
 524             print "</programlisting></example>\n";
 525         } else {
 526         }
 527         print " </simplesect>\n";
 528     }
 529
 530     print "</sect2>\n\n";
 531 }
 532
 533 ##
 534 # output in man
 535 sub output_man {
 536     my %args = %{$_[0]};
 537     my ($parameter, $section);
 538     my $count;
 539
 540     print ".TH \"$args{'module'}\" 3 \"$args{'function'}\" \"25 May 1998\" \"API Manual\" libfaim\n";
 541
 542     print ".SH NAME\n";
 543     print $args{'function'}." \\- ".$args{'purpose'}."\n";
 544
 545     print ".SH SYNOPSIS\n";
 546     print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n";
 547     $count = 0;
 548     $parenth = "(";
 549     $post = ",";
 550     foreach $parameter (@{$args{'parameterlist'}}) {
 551         if ($count == $#{$args{'parameterlist'}}) {
 552             $post = ");";
 553         }
 554         $type = $args{'parametertypes'}{$parameter};
 555         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 556             # pointer-to-function
 557             print ".BI \"".$parenth.$1."\" ".$parameter." \") (".$2.")".$post."\"\n";
 558         } else {
 559             $type =~ s/([^\*])$/\1 /;
 560             print ".BI \"".$parenth.$type."\" ".$parameter." \"".$post."\"\n";
 561         }
 562         $count++;
 563         $parenth = "";
 564     }
 565
 566     print ".SH Arguments\n";
 567     foreach $parameter (@{$args{'parameterlist'}}) {
 568         print ".IP \"".$parameter."\" 12\n";
 569         output_highlight($args{'parameters'}{$parameter});
 570     }
 571     foreach $section (@{$args{'sectionlist'}}) {
 572         print ".SH \"$section\"\n";
 573         output_highlight($args{'sections'}{$section});
 574     }
 575 }
 576
 577 sub output_intro_man {
 578     my %args = %{$_[0]};
 579     my ($parameter, $section);
 580     my $count;
 581
 582     print ".TH \"$args{'module'}\" 3 \"$args{'module'}\" \"25 May 1998\" \"API Manual\" libfaim\n";
 583
 584     foreach $section (@{$args{'sectionlist'}}) {
 585         print ".SH \"$section\"\n";
 586         output_highlight($args{'sections'}{$section});
 587     }
 588 }
 589
 590 ##
 591 # output in text
 592 sub output_text {
 593     my %args = %{$_[0]};
 594     my ($parameter, $section);
 595
 596     print "Function:\n\n";
 597     $start=$args{'functiontype'}." ".$args{'function'}." (";
 598     print $start;
 599     $count = 0;
 600     foreach $parameter (@{$args{'parameterlist'}}) {
 601         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 602             # pointer-to-function
 603             print $1.$parameter.") (".$2;
 604         } else {
 605             print $type." ".$parameter;
 606         }
 607         if ($count != $#{$args{'parameterlist'}}) {
 608             $count++;
 609             print ",\n";
 610             print " " x length($start);
 611         } else {
 612             print ");\n\n";
 613         }
 614     }
 615
 616     print "Arguments:\n\n";
 617     foreach $parameter (@{$args{'parameterlist'}}) {
 618         print $parameter."\n\t".$args{'parameters'}{$parameter}."\n";
 619     }
 620     foreach $section (@{$args{'sectionlist'}}) {
 621         print "$section:\n\n";
 622         output_highlight($args{'sections'}{$section});
 623     }
 624     print "\n\n";
 625 }
 626
 627 sub output_intro_text {
 628     my %args = %{$_[0]};
 629     my ($parameter, $section);
 630
 631     foreach $section (@{$args{'sectionlist'}}) {
 632         print " $section:\n";
 633         print "    -> ";
 634         output_highlight($args{'sections'}{$section});
 635     }
 636 }
 637
 638 ##
 639 # generic output function - calls the right one based
 640 # on current output mode.
 641 sub output_function {
 642 #    output_html(@_);
 643     eval "output_".$output_mode."(\@_);";
 644 }
 645
 646 ##
 647 # generic output function - calls the right one based
 648 # on current output mode.
 649 sub output_intro {
 650 #    output_html(@_);
 651     eval "output_intro_".$output_mode."(\@_);";
 652 }
 653
 654
 655 ##
 656 # takes a function prototype and spits out all the details
 657 # stored in the global arrays/hsahes.
 658 sub dump_function {
 659     my $prototype = shift @_;
 660
 661     $prototype =~ s/^static+ //;
 662     $prototype =~ s/^extern+ //;
 663     $prototype =~ s/^inline+ //;
 664     $prototype =~ s/^__inline__+ //;
 665     $prototype =~ s/^faim_export+ //;
 666     $prototype =~ s/^faim_internal+ //;
 667
 668     if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 669         $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 670         $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 671         $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 672         $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/)  {
 673         $return_type = $1;
 674         $function_name = $2;
 675         $args = $3;
 676
 677         # allow for up to fours args to function pointers
 678         $args =~ s/(\([^\),]+),/\1#/g;
 679         $args =~ s/(\([^\),]+),/\1#/g;
 680         $args =~ s/(\([^\),]+),/\1#/g;
 681 #       print STDERR "ARGS = '$args'\n";
 682
 683         foreach $arg (split ',', $args) {
 684             # strip leading/trailing spaces
 685             $arg =~ s/^\s*//;
 686             $arg =~ s/\s*$//;
 687
 688             if ($arg =~ m/\(/) {
 689                 # pointer-to-function
 690                 $arg =~ tr/#/,/;
 691                 $arg =~ m/[^\(]+\(\*([^\)]+)\)/;
 692                 $param = $1;
 693                 $type = $arg;
 694                 $type =~ s/([^\(]+\(\*)$param/\1/;
 695             } else {
 696                 # evil magic to get fixed array parameters to work
 697                 $arg =~ s/(.+\s+)(.+)\[.*/\1* \2/;
 698 #               print STDERR "SCAN ARG: '$arg'\n";
 699                 @args = split('\s', $arg);
 700
 701 #               print STDERR " -> @args\n";
 702                 $param = pop @args;
 703 #               print STDERR " -> @args\n";
 704                 if ($param =~ m/^(\*+)(.*)/) {
 705                     $param = $2;
 706                     push @args, $1;
 707                 }
 708                 $type = join " ", @args;
 709             }
 710
 711             if ($type eq "" && $param eq "...")
 712             {
 713                 $type="...";
 714                 $param="...";
 715                 $parameters{"..."} = "variable arguments";
 716             }
 717             if ($type eq "")
 718             {
 719                 $type="";
 720                 $param="void";
 721                 $parameters{void} = "no arguments";
 722             }
 723             if ($parameters{$param} eq "") {
 724                 $parameters{$param} = "-- undescribed --";
 725                 print STDERR "Warning($file:$lineno): Function parameter '$param' not described in '$function_name'\n";
 726             }
 727
 728             push @parameterlist, $param;
 729             $parametertypes{$param} = $type;
 730 #           print STDERR "param = '$param', type = '$type'\n";
 731         }
 732     } else {
 733         print STDERR "Error($lineno): cannot understand prototype: '$prototype'\n";
 734         return;
 735     }
 736
 737     if ($function_only==0 ||
 738      ( $function_only == 1 && defined($function_table{$function_name})) ||
 739      ( $function_only == 2 && !defined($function_table{$function_name})))
 740     {
 741         output_function({'function' => $function_name,
 742                          'module' => $modulename,
 743                          'functiontype' => $return_type,
 744                          'parameterlist' => \@parameterlist,
 745                          'parameters' => \%parameters,
 746                          'parametertypes' => \%parametertypes,
 747                          'sectionlist' => \@sectionlist,
 748                          'sections' => \%sections,
 749                          'purpose' => $function_purpose
 750                          });
 751     }
 752 }
 753
 754 ######################################################################
 755 # main
 756 # states
 757 # 0 - normal code
 758 # 1 - looking for function name
 759 # 2 - scanning field start.
 760 # 3 - scanning prototype.
 761 $state = 0;
 762 $section = "";
 763
 764 $doc_special = "\@\%\$\&";
 765
 766 $doc_start = "^/\\*\\*\$";
 767 $doc_end = "\\*/";
 768 $doc_com = "\\s*\\*\\s*";
 769 $doc_func = $doc_com."(\\w+):?";
 770 $doc_sect = $doc_com."([".$doc_special."]?[\\w ]+):(.*)";
 771 $doc_content = $doc_com."(.*)";
 772 $doc_block = $doc_com."DOC:\\s*(.*)?";
 773
 774 %constants = ();
 775 %parameters = ();
 776 @parameterlist = ();
 777 %sections = ();
 778 @sectionlist = ();
 779
 780 $contents = "";
 781 $section_default = "Description";       # default section
 782 $section_intro = "Introduction";
 783 $section = $section_default;
 784
 785 $lineno = 0;
 786 foreach $file (@ARGV) {
 787     chomp($file);
 788     if (!open(IN,"<$file")) {
 789         print STDERR "Error: Cannot open file $file\n";
 790         next;
 791     }
 792     while (<IN>) {
 793         $lineno++;
 794
 795         if ($state == 0) {
 796             if (/$doc_start/o) {
 797                 $state = 1;             # next line is always the function name
 798             }
 799         } elsif ($state == 1) { # this line is the function name (always)
 800             if (/$doc_block/o) {
 801                 $state = 4;
 802                 $contents = "";
 803                 if ( $1 eq "" ) {
 804                         $section = $section_intro;
 805                 } else {
 806                         $section = $1;
 807                 }
 808             }
 809             elsif (/$doc_func/o) {
 810                 $function = $1;
 811                 $state = 2;
 812                 if (/-(.*)/) {
 813                     $function_purpose = $1;
 814                 } else {
 815                     $function_purpose = "";
 816                 }
 817                 if ($verbose) {
 818                     print STDERR "Info($lineno): Scanning doc for $function\n";
 819                 }
 820             } else {
 821                 print STDERR "WARN($lineno): Cannot understand $_ on line $lineno",
 822                 " - I thought it was a doc line\n";
 823                 $state = 0;
 824             }
 825         } elsif ($state == 2) { # look for head: lines, and include content
 826             if (/$doc_sect/o) {
 827                 $newsection = $1;
 828                 $newcontents = $2;
 829
 830                 if ($contents ne "") {
 831                     $contents =~ s/\&/\\\\\\amp;/g;
 832                     $contents =~ s/\</\\\\\\lt;/g;
 833                     $contents =~ s/\>/\\\\\\gt;/g;
 834                     dump_section($section, $contents);
 835                     $section = $section_default;
 836                 }
 837
 838                 $contents = $newcontents;
 839                 if ($contents ne "") {
 840                     $contents .= "\n";
 841                 }
 842                 $section = $newsection;
 843             } elsif (/$doc_end/) {
 844
 845                 if ($contents ne "") {
 846                     $contents =~ s/\&/\\\\\\amp;/g;
 847                     $contents =~ s/\</\\\\\\lt;/g;
 848                     $contents =~ s/\>/\\\\\\gt;/g;
 849                     dump_section($section, $contents);
 850                     $section = $section_default;
 851                     $contents = "";
 852                 }
 853
 854 #           print STDERR "end of doc comment, looking for prototype\n";
 855                 $prototype = "";
 856                 $state = 3;
 857             } elsif (/$doc_content/) {
 858                 # miguel-style comment kludge, look for blank lines after
 859                 # @parameter line to signify start of description
 860                 if ($1 eq "" && $section =~ m/^@/) {
 861                     $contents =~ s/\&/\\\\\\amp;/g;
 862                     $contents =~ s/\</\\\\\\lt;/g;
 863                     $contents =~ s/\>/\\\\\\gt;/g;
 864                     dump_section($section, $contents);
 865                     $section = $section_default;
 866                     $contents = "";
 867                 } else {
 868                     $contents .= $1."\n";
 869                 }
 870             } else {
 871                 # i dont know - bad line?  ignore.
 872                 print STDERR "WARNING($lineno): bad line: $_";
 873             }
 874         } elsif ($state == 3) { # scanning for function { (end of prototype)
 875             if (m#\s*/\*\s+MACDOC\s*#io) {
 876               # do nothing
 877             }
 878             elsif (/([^\{]*)/) {
 879                 $prototype .= $1;
 880             }
 881             if (/\{/) {
 882                 $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
 883                 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
 884                 $prototype =~ s@^ +@@gos; # strip leading spaces
 885                 dump_function($prototype);
 886
 887                 $function = "";
 888                 %constants = ();
 889                 %parameters = ();
 890                 %parametertypes = ();
 891                 @parameterlist = ();
 892                 %sections = ();
 893                 @sectionlist = ();
 894                 $prototype = "";
 895
 896                 $state = 0;
 897             }
 898         } elsif ($state == 4) {
 899                 # Documentation block
 900                 if (/$doc_block/) {
 901                         dump_section($section, $contents);
 902                         output_intro({'sectionlist' => \@sectionlist,
 903                                       'sections' => \%sections });
 904                         $contents = "";
 905                         $function = "";
 906                         %constants = ();
 907                         %parameters = ();
 908                         %parametertypes = ();
 909                         @parameterlist = ();
 910                         %sections = ();
 911                         @sectionlist = ();
 912                         $prototype = "";
 913                         if ( $1 eq "" ) {
 914                                 $section = $section_intro;
 915                         } else {
 916                                 $section = $1;
 917                         }
 918                 }
 919                 elsif (/$doc_end/)
 920                 {
 921                         dump_section($section, $contents);
 922                         output_intro({'sectionlist' => \@sectionlist,
 923                                       'sections' => \%sections });
 924                         $contents = "";
 925                         $function = "";
 926                         %constants = ();
 927                         %parameters = ();
 928                         %parametertypes = ();
 929                         @parameterlist = ();
 930                         %sections = ();
 931                         @sectionlist = ();
 932                         $prototype = "";
 933                         $state = 0;
 934                 }
 935                 elsif (/$doc_content/)
 936                 {
 937                         if ( $1 eq "" )
 938                         {
 939                                 $contents .= $blankline;
 940                         }
 941                         else
 942                         {
 943                                 $contents .= $1 . "\n";
 944                         }
 945                 }
 946           }
 947     }
 948 }
 949