gdoc

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