doc/gdoc

   1 #!/usr/bin/perl
   2
   3 ## Copyright (c) 2003 Simon Josefsson                            ##
   4 ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved        ##
   5 ##                    hacked to allow -tex option --nmav         ##
   6 ##                    hacked to allow -texinfo option --jas      ##
   7 ##                                                               ##
   8 ## This software falls under the GNU Public License. Please read ##
   9 ##              the COPYING file for more information            ##
  10
  11 #
  12 # This will read a 'c' file and scan for embedded comments in the
  13 # style of gnome comments (+minor extensions - see below).
  14 #
  15 # This program is modified by Nikos Mavroyanopoulos, for the gnutls
  16 # project.
  17
  18 # This program is modified by Simon Josefsson, for the Libidn and
  19 # Shishi project.
  20
  21 # Note: This only supports 'c'.
  22
  23 # usage:
  24 # gdoc [ -docbook | -html | -text | -man | -tex | -texinfo | -listfunc ]
  25 #      [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
  26 #
  27 #  Set output format using one of -docbook -html -text -man -tex or
  28 #  -texinfo.  Default is man.
  29 #
  30 #  -function funcname
  31 #       If set, then only generate documentation for the given
  32 #       function(s).  All other functions are ignored.
  33 #
  34 #  c files - list of 'c' files to process
  35 #
  36 #  All output goes to stdout, with errors to stderr.
  37
  38 #
  39 # format of comments.
  40 # In the following table, (...)? signifies optional structure.
  41 #                         (...)* signifies 0 or more structure elements
  42 # /**
  43 #  * function_name(:)? (- short description)?
  44 # (* @parameterx: (description of parameter x)?)*
  45 # (* a blank line)?
  46 #  * (Description:)? (Description of function)?
  47 #  * (section header: (section description)? )*
  48 #  (*)?*/
  49 #
  50 # So .. the trivial example would be:
  51 #
  52 # /**
  53 #  * my_function
  54 #  **/
  55 #
  56 # If the Description: header tag is ommitted, then there must be a blank line
  57 # after the last parameter specification.
  58 # e.g.
  59 # /**
  60 #  * my_function - does my stuff
  61 #  * @my_arg: its mine damnit
  62 #  *
  63 #  * Does my stuff explained.
  64 #  */
  65 #
  66 #  or, could also use:
  67 # /**
  68 #  * my_function - does my stuff
  69 #  * @my_arg: its mine damnit
  70 #  * Description: Does my stuff explained.
  71 #  */
  72 # etc.
  73 #
  74 # All descriptions can be multiline, apart from the short function description.
  75 #
  76 # All descriptive text is further processed, scanning for the following special
  77 # patterns, which are highlighted appropriately.
  78 #
  79 # 'funcname()' - function
  80 # '$ENVVAR' - environmental variable
  81 # '&struct_name' - name of a structure
  82 # '@parameter' - name of a parameter
  83 # '%CONST' - name of a constant.
  84
  85 #
  86 # Extensions for LaTeX:
  87 #
  88 # 1. the symbol '->' will be replaced with a rightarrow
  89 # 2. x^y with ${x}^{y}$.
  90 # 3. xxx\: with xxx:
  91
  92 use POSIX qw(strftime);
  93
  94 # match expressions used to find embedded type information
  95 $type_constant = "\\\%(\\w+)";
  96 $type_func = "(\\w+\\(\\))";
  97 #$type_func = "(\\(w||\\\\)+\\(\\))";
  98 $type_param = "\\\@(\\w+)";
  99 $type_struct = "\\\&(\\w+)";
 100 $type_env = "(\\\$\\w+)";
 101
 102
 103 # Output conversion substitutions.
 104 #  One for each output format
 105
 106 # these work fairly well
 107 %highlights_html = ( $type_constant, "<i>\$1</i>",
 108                      $type_func, "<b>\$1</b>",
 109                      $type_struct, "<i>\$1</i>",
 110                      $type_param, "<tt><b>\$1</b></tt>" );
 111 $blankline_html = "<p>";
 112
 113 $at = '@';
 114 %highlights_texinfo = ( $type_constant, "CMDvar{\$1}",
 115                         $type_func, "CMDcode{\$1}",
 116                         $type_struct, "CMDcode{\$1}",
 117                         $type_param, "CMDcode\{\$1\}" );
 118 $blankline_texinfo = "";
 119
 120 %highlights_tex = ( $type_constant, "{\\\\it \$1}",
 121                      $type_func, "{\\\\bf \$1}",
 122                      $type_struct, "{\\\\it \$1}",
 123                      $type_param, "{\\\\bf \$1}" );
 124 $blankline_tex = "\\par";
 125
 126 # sgml, docbook format
 127 %highlights_sgml = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",
 128                      $type_func, "<function>\$1</function>",
 129                      $type_struct, "<structname>\$1</structname>",
 130                      $type_env, "<envar>\$1</envar>",
 131                      $type_param, "<parameter>\$1</parameter>" );
 132 $blankline_sgml = "</para><para>\n";
 133
 134 # these are pretty rough
 135 %highlights_man = ( $type_constant, "\\n.I \\\"\$1\\\"\\n",
 136                     $type_func, "\\n.B \\\"\$1\\\"\\n",
 137                     $type_struct, "\\n.I \\\"\$1\\\"\\n",
 138                     $type_param."([\.\, ]*)\n?", "\\n.I \\\"\$1\$2\\\"\\n" );
 139 $blankline_man = "";
 140
 141 # text-mode
 142 %highlights_text = ( $type_constant, "\$1",
 143                      $type_func, "\$1",
 144                      $type_struct, "\$1",
 145                      $type_param, "\$1" );
 146 $blankline_text = "";
 147
 148
 149 sub usage {
 150     print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man |\n";
 151     print "                   -tex | -texinfo | -listfunc ]\n";
 152     print "         [ -function funcname [ -function funcname ...] ]\n";
 153     print "         c source file(s) > outputfile\n";
 154     exit 1;
 155 }
 156
 157 # read arguments
 158 if ($#ARGV==-1) {
 159     usage();
 160 }
 161
 162 $verbose = 0;
 163 $output_mode = "man";
 164 %highlights = %highlights_man;
 165 $blankline = $blankline_man;
 166 $modulename = "API Documentation";
 167 $version = strftime "%Y-%m-%d", localtime;
 168 $function_only = 0;
 169 while ($ARGV[0] =~ m/^-(.*)/) {
 170     $cmd = shift @ARGV;
 171     if ($cmd eq "-html") {
 172         $output_mode = "html";
 173         %highlights = %highlights_html;
 174         $blankline = $blankline_html;
 175     } elsif ($cmd eq "-man") {
 176         $output_mode = "man";
 177         %highlights = %highlights_man;
 178         $blankline = $blankline_man;
 179     } elsif ($cmd eq "-tex") {
 180         $output_mode = "tex";
 181         %highlights = %highlights_tex;
 182         $blankline = $blankline_tex;
 183     } elsif ($cmd eq "-texinfo") {
 184         $output_mode = "texinfo";
 185         %highlights = %highlights_texinfo;
 186         $blankline = $blankline_texinfo;
 187     } elsif ($cmd eq "-text") {
 188         $output_mode = "text";
 189         %highlights = %highlights_text;
 190         $blankline = $blankline_text;
 191     } elsif ($cmd eq "-docbook") {
 192         $output_mode = "sgml";
 193         %highlights = %highlights_sgml;
 194         $blankline = $blankline_sgml;
 195     } elsif ($cmd eq "-listfunc") {
 196         $output_mode = "listfunc";
 197     } elsif ($cmd eq "-module") { # not needed for sgml, inherits from calling document
 198         $modulename = shift @ARGV;
 199     } elsif ($cmd eq "-version") {
 200         $version = shift @ARGV;
 201     } elsif ($cmd eq "-function") { # to only output specific functions
 202         $function_only = 1;
 203         $function = shift @ARGV;
 204         $function_table{$function} = 1;
 205     } elsif ($cmd eq "-v") {
 206         $verbose = 1;
 207     } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
 208         usage();
 209     }
 210 }
 211
 212
 213 # generate a sequence of code that will splice in highlighting information
 214 # using the s// operator.
 215 $dohighlight = "";
 216 foreach $pattern (keys %highlights) {
 217 #    print STDERR "scanning pattern $pattern ($highlights{$pattern})\n";
 218     $dohighlight .=  "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
 219 }
 220
 221 ##
 222 # dumps section contents to arrays/hashes intended for that purpose.
 223 #
 224 sub dump_section {
 225     my $name = shift @_;
 226     my $contents = join "\n", @_;
 227
 228     if ($name =~ m/$type_constant/) {
 229         $name = $1;
 230 #       print STDERR "constant section '$1' = '$contents'\n";
 231         $constants{$name} = $contents;
 232     } elsif ($name =~ m/$type_param/) {
 233 #       print STDERR "parameter def '$1' = '$contents'\n";
 234         $name = $1;
 235         $parameters{$name} = $contents;
 236     } else {
 237 #       print STDERR "other section '$name' = '$contents'\n";
 238         $sections{$name} = $contents;
 239         push @sectionlist, $name;
 240     }
 241 }
 242
 243 ##
 244 # output function
 245 #
 246 # parameters, a hash.
 247 #  function => "function name"
 248 #  parameterlist => @list of parameters
 249 #  parameters => %parameter descriptions
 250 #  sectionlist => @list of sections
 251 #  sections => %descriont descriptions
 252 #
 253
 254 sub output_highlight {
 255     my $contents = join "\n", @_;
 256     my $line;
 257
 258     if (substr($contents, 0, 1) eq " ") {
 259         $contents = substr($contents, 1);
 260     }
 261
 262     $contents =~ s:{:\@{:gs if ($output_mode eq "texinfo");
 263     $contents =~ s:}:\@}:gs if ($output_mode eq "texinfo");
 264     eval $dohighlight;
 265     $contents =~ s:CMD:@:gs if ($output_mode eq "texinfo");
 266     foreach $line (split "\n", $contents) {
 267         if ($line eq ""){
 268             print $lineprefix, $blankline;
 269         } else {
 270             print $lineprefix, $line;
 271         }
 272         print "\n";
 273     }
 274 }
 275
 276 # output in texinfo
 277 sub output_texinfo {
 278     my %args = %{$_[0]};
 279     my ($parameter, $section);
 280     my $count;
 281
 282     print "\@deftypefun {";
 283     print $args{'functiontype'};
 284     print "} ".$args{'function'}." ";
 285     print "(";
 286     $count = 0;
 287     foreach $parameter (@{$args{'parameterlist'}}) {
 288         print $args{'parametertypes'}{$parameter}." \@var{".$parameter."}";
 289         if ($count != $#{$args{'parameterlist'}}) {
 290             $count++;
 291             print ", ";
 292         }
 293     }
 294     print ")\n\n";
 295     foreach $parameter (@{$args{'parameterlist'}}) {
 296         if ($args{'parameters'}{$parameter}) {
 297             print "\@var{".$parameter."}: ";
 298             output_highlight($args{'parameters'}{$parameter});
 299             print "\n";
 300         }
 301     }
 302     foreach $section (@{$args{'sectionlist'}}) {
 303         output_highlight($args{'sections'}{$section});
 304         print "\n";
 305     }
 306     print "\@end deftypefun\n\n";
 307 }
 308
 309 # output in html
 310 sub output_html {
 311     my %args = %{$_[0]};
 312     my ($parameter, $section);
 313     my $count;
 314     print "\n\n<a name=\"". $args{'function'} . "\">&nbsp</a><h2>Function</h2>\n";
 315
 316     print "<i>".$args{'functiontype'}."</i>\n";
 317     print "<b>".$args{'function'}."</b>\n";
 318     print "(";
 319     $count = 0;
 320     foreach $parameter (@{$args{'parameterlist'}}) {
 321         print "<i>".$args{'parametertypes'}{$parameter}."</i> <b>".$parameter."</b>\n";
 322         if ($count != $#{$args{'parameterlist'}}) {
 323             $count++;
 324             print ", ";
 325         }
 326     }
 327     print ")\n";
 328
 329     print "<h3>Arguments</h3>\n";
 330     print "<dl>\n";
 331     foreach $parameter (@{$args{'parameterlist'}}) {
 332         print "<dt><i>".$args{'parametertypes'}{$parameter}."</i> <b>".$parameter."</b>\n";
 333         print "<dd>";
 334         output_highlight($args{'parameters'}{$parameter});
 335     }
 336     print "</dl>\n";
 337     foreach $section (@{$args{'sectionlist'}}) {
 338         print "<h3>$section</h3>\n";
 339         print "<ul>\n";
 340         output_highlight($args{'sections'}{$section});
 341         print "</ul>\n";
 342     }
 343     print "<hr>\n";
 344 }
 345
 346 # output in tex
 347 sub output_tex {
 348     my %args = %{$_[0]};
 349     my ($parameter, $section);
 350     my $count;
 351     my $func = $args{'function'};
 352     my $param;
 353     my $param2;
 354     my $sec;
 355     my $check;
 356     my $type;
 357
 358     $func =~ s/_/\\_/g;
 359
 360     print "\n\n\\subsection{". $func . "}\n\\label{" . $args{'function'} . "}\n";
 361
 362     $type = $args{'functiontype'};
 363     $type =~ s/_/\\_/g;
 364
 365     print "{\\it ".$type."}\n";
 366     print "{\\bf ".$func."}\n";
 367     print "(\n";
 368     $count = 0;
 369     foreach $parameter (@{$args{'parameterlist'}}) {
 370         $param = $args{'parametertypes'}{$parameter};
 371         $param2 = $parameter;
 372         $param =~ s/_/\\_/g;
 373         $param2 =~ s/_/\\_/g;
 374
 375         print "{\\it ".$param."} {\\bf ".$param2."}\n";
 376         if ($count != $#{$args{'parameterlist'}}) {
 377             $count++;
 378             print ", ";
 379         }
 380     }
 381     print ")\n";
 382
 383     print "\n{\\large{Arguments}}\n";
 384
 385     print "\\begin{itemize}\n";
 386     $check=0;
 387     foreach $parameter (@{$args{'parameterlist'}}) {
 388         $param1 = $args{'parametertypes'}{$parameter};
 389         $param1 =~ s/_/\\_/g;
 390         $param2 = $parameter;
 391         $param2 =~ s/_/\\_/g;
 392
 393         $check = 1;
 394         print "\\item {\\it ".$param1."} {\\bf ".$param2."}: \n";
 395 #       print "\n";
 396
 397         $param3 = $args{'parameters'}{$parameter};
 398         $param3 =~ s/_/\\_/g;
 399         $param3 =~ s/&([a-zA-Z\_]+)/{\\it \1}/g;
 400
 401         output_highlight($param3);
 402     }
 403     if ($check==0) {
 404         print "\\item void\n";
 405     }
 406     print "\\end{itemize}\n";
 407
 408     foreach $section (@{$args{'sectionlist'}}) {
 409         $sec = $section;
 410         $sec =~ s/_/\\_/g;
 411         $sec =~ s/&([a-zA-Z\_]+)/{\\it \1}/g;
 412
 413         print "\n\\par{\\large{$sec}}\\par\n";
 414         print "\\begin{rmfamily}\n";
 415
 416         $sec = $args{'sections'}{$section};
 417         $sec =~ s/_/\\_/g;
 418         $sec =~ s/\\:/:/g;
 419         $sec =~ s/&([a-zA-Z\_]+)/{\\it \1}/g;
 420         $sec =~ s/->/\$\\rightarrow\$/g;
 421         $sec =~ s/([0-9]+)\^([0-9]+)/\$\{\1\}\^\{\2\}\$/g;
 422
 423         output_highlight($sec);
 424         print "\\end{rmfamily}\n";
 425     }
 426     print "\n";
 427 }
 428
 429
 430 # output in sgml DocBook
 431 sub output_sgml {
 432     my %args = %{$_[0]};
 433     my ($parameter, $section);
 434     my $count;
 435     my $id;
 436
 437     $id = $args{'module'}."-".$args{'function'};
 438     $id =~ s/[^A-Za-z0-9]/-/g;
 439
 440     print "<refentry>\n";
 441     print "<refmeta>\n";
 442     print "<refentrytitle><phrase id=\"$id\">".$args{'function'}."</phrase></refentrytitle>\n";
 443     print "</refmeta>\n";
 444     print "<refnamediv>\n";
 445     print " <refname>".$args{'function'}."</refname>\n";
 446     print " <refpurpose>\n";
 447     print "  ".$args{'purpose'}."\n";
 448     print " </refpurpose>\n";
 449     print "</refnamediv>\n";
 450
 451     print "<refsynopsisdiv>\n";
 452     print " <title>Synopsis</title>\n";
 453     print "  <funcsynopsis>\n";
 454     print "   <funcdef>".$args{'functiontype'}." ";
 455     print "<function>".$args{'function'}." ";
 456     print "</function></funcdef>\n";
 457
 458 #    print "<refsect1>\n";
 459 #    print " <title>Synopsis</title>\n";
 460 #    print "  <funcsynopsis>\n";
 461 #    print "   <funcdef>".$args{'functiontype'}." ";
 462 #    print "<function>".$args{'function'}." ";
 463 #    print "</function></funcdef>\n";
 464
 465     $count = 0;
 466     if ($#{$args{'parameterlist'}} >= 0) {
 467         foreach $parameter (@{$args{'parameterlist'}}) {
 468             print "   <paramdef>".$args{'parametertypes'}{$parameter};
 469             print " <parameter>$parameter</parameter></paramdef>\n";
 470         }
 471     } else {
 472         print "  <void>\n";
 473     }
 474     print "  </funcsynopsis>\n";
 475     print "</refsynopsisdiv>\n";
 476 #    print "</refsect1>\n";
 477
 478     # print parameters
 479     print "<refsect1>\n <title>Arguments</title>\n";
 480 #    print "<para>\nArguments\n";
 481     if ($#{$args{'parameterlist'}} >= 0) {
 482         print " <variablelist>\n";
 483         foreach $parameter (@{$args{'parameterlist'}}) {
 484             print "  <varlistentry>\n   <term><parameter>$parameter</parameter></term>\n";
 485             print "   <listitem>\n    <para>\n";
 486             $lineprefix="     ";
 487             output_highlight($args{'parameters'}{$parameter});
 488             print "    </para>\n   </listitem>\n  </varlistentry>\n";
 489         }
 490         print " </variablelist>\n";
 491     } else {
 492         print " <para>\n  None\n </para>\n";
 493     }
 494     print "</refsect1>\n";
 495
 496     # print out each section
 497     $lineprefix="   ";
 498     foreach $section (@{$args{'sectionlist'}}) {
 499         print "<refsect1>\n <title>$section</title>\n <para>\n";
 500 #       print "<para>\n$section\n";
 501         if ($section =~ m/EXAMPLE/i) {
 502             print "<example><para>\n";
 503         }
 504         output_highlight($args{'sections'}{$section});
 505 #       print "</para>";
 506         if ($section =~ m/EXAMPLE/i) {
 507             print "</para></example>\n";
 508         }
 509         print " </para>\n</refsect1>\n";
 510     }
 511
 512     print "\n\n";
 513 }
 514
 515 ##
 516 # output in man
 517 sub output_man {
 518     my %args = %{$_[0]};
 519     my ($parameter, $section);
 520     my $count;
 521
 522     print ".TH \"$args{'function'}\" 3 \"$args{'version'}\" \"GNU\" \"". uc($args{'module'}) . "\"\n";
 523
 524     print ".SH NAME\n";
 525
 526     print $args{'function'}."\n";
 527
 528     print ".SH SYNOPSIS\n";
 529     print ".B #include <". lc($args{'module'}) . ".h>\n";
 530     print ".sp\n";
 531     print ".BI \"".$args{'functiontype'}." ".$args{'function'}."(";
 532     $count = 0;
 533     foreach $parameter (@{$args{'parameterlist'}}) {
 534         print $args{'parametertypes'}{$parameter}." \" ".$parameter." \"";
 535         if ($count != $#{$args{'parameterlist'}}) {
 536             $count++;
 537             print ", ";
 538         }
 539     }
 540     print ");\"\n";
 541
 542     print ".SH ARGUMENTS\n";
 543     foreach $parameter (@{$args{'parameterlist'}}) {
 544         print ".IP \"".$args{'parametertypes'}{$parameter}." ".$parameter."\" 12\n";
 545         output_highlight($args{'parameters'}{$parameter});
 546     }
 547     foreach $section (@{$args{'sectionlist'}}) {
 548         print ".SH \"" . uc($section) . "\"\n";
 549         output_highlight($args{'sections'}{$section});
 550     }
 551     print ".SH \"REPORTING BUGS\"\n";
 552     print "Report bugs to <bug-". lc($args{'module'}) . "\@josefsson.org>.\n";
 553     print ".SH COPYRIGHT\n";
 554     print "Copyright \\(co 2002, 2003 Simon Josefsson.\n";
 555     print ".br\n";
 556     print "Permission is granted to copy, distribute and/or modify this document\n";
 557     print "under the terms of the GNU Free Documentation License, Version 1.1\n";
 558     print "or any later version published by the Free Software Foundation.\n";
 559     print ".SH \"SEE ALSO\"\n";
 560     print "The full documentation for\n";
 561     print ".B " . ucfirst($args{'module'}) . "\n";
 562     print "is maintained as a Texinfo manual.  If the\n";
 563     print ".B info\n";
 564     print "and\n";
 565     print ".B " . lc($args{'module'}) . "\n";
 566     print "programs are properly installed at your site, the command\n";
 567     print ".IP\n";
 568     print ".B info " . lc($args{'module'}) . "\n";
 569     print ".PP\n";
 570     print "should give you access to the complete manual.\n";
 571 }
 572
 573 sub output_listfunc {
 574     my %args = %{$_[0]};
 575     print $args{'function'} . "\n";
 576 }
 577
 578 ##
 579 # output in text
 580 sub output_text {
 581     my %args = %{$_[0]};
 582     my ($parameter, $section);
 583
 584     print "Function = ".$args{'function'}."\n";
 585     print "  return type: ".$args{'functiontype'}."\n\n";
 586     foreach $parameter (@{$args{'parameterlist'}}) {
 587         print " ".$args{'parametertypes'}{$parameter}." ".$parameter."\n";
 588         print "    -> ".$args{'parameters'}{$parameter}."\n";
 589     }
 590     foreach $section (@{$args{'sectionlist'}}) {
 591         print " $section:\n";
 592         print "    -> ";
 593         output_highlight($args{'sections'}{$section});
 594     }
 595 }
 596
 597 ##
 598 # generic output function - calls the right one based
 599 # on current output mode.
 600 sub output_function {
 601 #    output_html(@_);
 602     eval "output_".$output_mode."(\@_);";
 603 }
 604
 605
 606 ##
 607 # takes a function prototype and spits out all the details
 608 # stored in the global arrays/hsahes.
 609 sub dump_function {
 610     my $prototype = shift @_;
 611
 612     if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ ||
 613         $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ ||
 614         $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ ||
 615         $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ ||
 616         $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/)  {
 617         $return_type = $1;
 618         $function_name = $2;
 619         $args = $3;
 620
 621 #       print STDERR "ARGS = '$args'\n";
 622
 623         foreach $arg (split ',', $args) {
 624             # strip leading/trailing spaces
 625             $arg =~ s/^\s*//;
 626             $arg =~ s/\s*$//;
 627 #           print STDERR "SCAN ARG: '$arg'\n";
 628             @args = split('\s', $arg);
 629
 630 #           print STDERR " -> @args\n";
 631             $param = pop @args;
 632 #           print STDERR " -> @args\n";
 633             if ($param =~ m/^(\*+)(.*)/) {
 634                 $param = $2;
 635                 push @args, $1;
 636             }
 637             $type = join " ", @args;
 638
 639             if ($parameters{$param} eq "" && $param != "void") {
 640                 $parameters{$param} = "-- undescribed --";
 641                 print STDERR "Warning($lineno): Function parameter '$param' not described in '$function_name'\n";
 642             }
 643
 644             push @parameterlist, $param;
 645             $parametertypes{$param} = $type;
 646
 647 #           print STDERR "param = '$param', type = '$type'\n";
 648         }
 649     } else {
 650         print STDERR "Error($lineno): cannot understand prototype: '$prototype'\n";
 651         return;
 652     }
 653
 654     if ($function_only==0 || defined($function_table{$function_name})) {
 655         output_function({'function' => $function_name,
 656                          'module' => $modulename,
 657                          'version' => $version,
 658                          'functiontype' => $return_type,
 659                          'parameterlist' => \@parameterlist,
 660                          'parameters' => \%parameters,
 661                          'parametertypes' => \%parametertypes,
 662                          'sectionlist' => \@sectionlist,
 663                          'sections' => \%sections,
 664                          'purpose' => $function_purpose
 665                          });
 666     }
 667 }
 668
 669 ######################################################################
 670 # main
 671 # states
 672 # 0 - normal code
 673 # 1 - looking for function name
 674 # 2 - scanning field start.
 675 # 3 - scanning prototype.
 676 $state = 0;
 677 $section = "";
 678
 679 $doc_special = "\@\%\$\&";
 680
 681 $doc_start = "^/\\*\\*\$";
 682 $doc_end = "\\*/";
 683 $doc_com = "\\s*\\*\\s*";
 684 $doc_func = $doc_com."(\\w+):?";
 685 $doc_sect = $doc_com."([".$doc_special."]?[\\w ]+):(.*)";
 686 $doc_content = $doc_com."(.*)";
 687
 688 %constants = ();
 689 %parameters = ();
 690 @parameterlist = ();
 691 %sections = ();
 692 @sectionlist = ();
 693
 694 $contents = "";
 695 $section_default = "Description";       # default section
 696 $section = $section_default;
 697
 698 $lineno = 0;
 699 foreach $file (@ARGV) {
 700     if (!open(IN,"<$file")) {
 701         print STDERR "Error: Cannot open file $file\n";
 702         next;
 703     }
 704     while (<IN>) {
 705         $lineno++;
 706
 707         if ($state == 0) {
 708             if (/$doc_start/o) {
 709                 $state = 1;             # next line is always the function name
 710             }
 711         } elsif ($state == 1) { # this line is the function name (always)
 712             if (/$doc_func/o) {
 713                 $function = $1;
 714                 $state = 2;
 715                 if (/-(.*)/) {
 716                     $function_purpose = $1;
 717                 } else {
 718                     $function_purpose = "";
 719                 }
 720                 if ($verbose) {
 721                     print STDERR "Info($lineno): Scanning doc for $function\n";
 722                 }
 723             } else {
 724                 print STDERR "WARN($lineno): Cannot understand $_ on line $lineno",
 725                 " - I thought it was a doc line\n";
 726                 $state = 0;
 727             }
 728         } elsif ($state == 2) { # look for head: lines, and include content
 729             if (/$doc_sect/o) {
 730                 $newsection = $1;
 731                 $newcontents = $2;
 732
 733                 if ($contents ne "") {
 734                     dump_section($section, $contents);
 735                     $section = $section_default;
 736                 }
 737
 738                 $contents = $newcontents;
 739                 if ($contents ne "") {
 740                     $contents .= "\n";
 741                 }
 742                 $section = $newsection;
 743             } elsif (/$doc_end/) {
 744
 745                 if ($contents ne "") {
 746                     dump_section($section, $contents);
 747                     $section = $section_default;
 748                     $contents = "";
 749                 }
 750
 751 #           print STDERR "end of doc comment, looking for prototype\n";
 752                 $prototype = "";
 753                 $state = 3;
 754             } elsif (/$doc_content/) {
 755                 # miguel-style comment kludge, look for blank lines after
 756                 # @parameter line to signify start of description
 757                 if ($1 eq "" && $section =~ m/^@/) {
 758                     dump_section($section, $contents);
 759                     $section = $section_default;
 760                     $contents = "";
 761                 } else {
 762                     $contents .= $1."\n";
 763                 }
 764             } else {
 765                 # i dont know - bad line?  ignore.
 766                 print STDERR "WARNING($lineno): bad line: $_";
 767             }
 768         } elsif ($state == 3) { # scanning for function { (end of prototype)
 769             if (m#\s*/\*\s+MACDOC\s*#io) {
 770               # do nothing
 771             }
 772             elsif (/([^\{]*)/) {
 773                 $prototype .= $1;
 774             }
 775             if (/\{/) {
 776                 $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
 777                 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
 778                 $prototype =~ s@^ +@@gos; # strip leading spaces
 779                 dump_function($prototype);
 780
 781                 $function = "";
 782                 %constants = ();
 783                 %parameters = ();
 784                 %parametertypes = ();
 785                 @parameterlist = ();
 786                 %sections = ();
 787                 @sectionlist = ();
 788                 $prototype = "";
 789
 790                 $state = 0;
 791             }
 792         }
 793     }
 794 }
 795