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