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