gdoc

   1 #!/usr/bin/perl
   2
   3 ## Copyright (c) 2002, 2003 Simon Josefsson: -texinfo, -doxygen  ##
   4 ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved        ##
   5 ##                    hacked to allow -tex option --nmav         ##
   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 # The -doxygen parameter isn't used now (see gdoc2doxygen in libidn
  18 # for an alternative solution), but I kept it in case I want to use it
  19 # in the future.
  20
  21 # Note: This only supports 'c'.
  22
  23 # usage:
  24 # gdoc [ -docbook | -html | -text | -man | -tex | -texinfo ]
  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
  93 # match expressions used to find embedded type information
  94 $type_constant = "\\\%(\\w+)";
  95 $type_func = "(\\w+\\(\\))";
  96 #$type_func = "(\\(w||\\\\)+\\(\\))";
  97 $type_param = "\\\@(\\w+)";
  98 $type_struct = "\\\&(\\w+)";
  99 $type_env = "(\\\$\\w+)";
 100
 101
 102 # Output conversion substitutions.
 103 #  One for each output format
 104
 105 # these work fairly well
 106 %highlights_html = ( $type_constant, "<i>\$1</i>",
 107                      $type_func, "<b>\$1</b>",
 108                      $type_struct, "<i>\$1</i>",
 109                      $type_param, "<tt><b>\$1</b></tt>" );
 110 $blankline_html = "<p>";
 111
 112 $at = '@';
 113 %highlights_texinfo = ( $type_constant, "CMDvar{\$1}",
 114                         $type_func, "CMDcode{\$1}",
 115                         $type_struct, "CMDcode{\$1}",
 116                         $type_param, "CMDcode\{\$1\}" );
 117 $blankline_texinfo = "";
 118
 119 %highlights_tex = ( $type_constant, "{\\\\it \$1}",
 120                      $type_func, "{\\\\bf \$1}",
 121                      $type_struct, "{\\\\it \$1}",
 122                      $type_param, "{\\\\bf \$1}" );
 123 $blankline_tex = "\\par";
 124
 125 # sgml, docbook format
 126 %highlights_sgml = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",
 127                      $type_func, "<function>\$1</function>",
 128                      $type_struct, "<structname>\$1</structname>",
 129                      $type_env, "<envar>\$1</envar>",
 130                      $type_param, "<parameter>\$1</parameter>" );
 131 $blankline_sgml = "</para><para>\n";
 132
 133 # these are pretty rough
 134 %highlights_man = ( $type_constant, "\\n.I \\\"\$1\\\"\\n",
 135                     $type_func, "\\n.B \\\"\$1\\\"\\n",
 136                     $type_struct, "\\n.I \\\"\$1\\\"\\n",
 137                     $type_param."([\.\, ]*)\n?", "\\n.I \\\"\$1\$2\\\"\\n" );
 138 $blankline_man = "";
 139
 140 # text-mode
 141 %highlights_text = ( $type_constant, "\$1",
 142                      $type_func, "\$1",
 143                      $type_struct, "\$1",
 144                      $type_param, "\$1" );
 145 $blankline_text = "";
 146
 147 $bs="\\";
 148 %highlights_doxygen = ( $type_constant, "\${bs}var \$1",
 149                         $type_func, "\${bs}fn \$1",
 150                         $type_struct, "\${bs}typedef \$1",
 151                         $type_param, "\${bs}param \$1" );
 152 $blankline_doxygen = "\\n";
 153
 154
 155 sub usage {
 156     print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man | -tex | -texinfo | -doxygen ]\n";
 157     print "         [ -function funcname [ -function funcname ...] ]\n";
 158     print "         c source file(s) > outputfile\n";
 159     exit 1;
 160 }
 161
 162 # read arguments
 163 if ($#ARGV==-1) {
 164     usage();
 165 }
 166
 167 $verbose = 0;
 168 $output_mode = "man";
 169 %highlights = %highlights_man;
 170 $blankline = $blankline_man;
 171 $modulename = "API Documentation";
 172 $function_only = 0;
 173 while ($ARGV[0] =~ m/^-(.*)/) {
 174     $cmd = shift @ARGV;
 175     if ($cmd eq "-html") {
 176         $output_mode = "html";
 177         %highlights = %highlights_html;
 178         $blankline = $blankline_html;
 179     } elsif ($cmd eq "-man") {
 180         $output_mode = "man";
 181         %highlights = %highlights_man;
 182         $blankline = $blankline_man;
 183     } elsif ($cmd eq "-tex") {
 184         $output_mode = "tex";
 185         %highlights = %highlights_tex;
 186         $blankline = $blankline_tex;
 187     } elsif ($cmd eq "-texinfo") {
 188         $output_mode = "texinfo";
 189         %highlights = %highlights_texinfo;
 190         $blankline = $blankline_texinfo;
 191     } elsif ($cmd eq "-text") {
 192         $output_mode = "text";
 193         %highlights = %highlights_text;
 194         $blankline = $blankline_text;
 195     } elsif ($cmd eq "-docbook") {
 196         $output_mode = "sgml";
 197         %highlights = %highlights_sgml;
 198         $blankline = $blankline_sgml;
 199     } elsif ($cmd eq "-doxygen") {
 200         $output_mode = "doxygen";
 201         %highlights = %highlights_doxygen;
 202         $blankline = $blankline_doxygen;
 203     } elsif ($cmd eq "-module") { # not needed for sgml, inherits from calling document
 204         $modulename = shift @ARGV;
 205     } elsif ($cmd eq "-function") { # to only output specific functions
 206         $function_only = 1;
 207         $function = shift @ARGV;
 208         $function_table{$function} = 1;
 209     } elsif ($cmd eq "-v") {
 210         $verbose = 1;
 211     } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
 212         usage();
 213     }
 214 }
 215
 216
 217 # generate a sequence of code that will splice in highlighting information
 218 # using the s// operator.
 219 $dohighlight = "";
 220 foreach $pattern (keys %highlights) {
 221 #    print STDERR "scanning pattern $pattern ($highlights{$pattern})\n";
 222     $dohighlight .=  "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
 223 }
 224
 225 ##
 226 # dumps section contents to arrays/hashes intended for that purpose.
 227 #
 228 sub dump_section {
 229     my $name = shift @_;
 230     my $contents = join "\n", @_;
 231
 232     if ($name =~ m/$type_constant/) {
 233         $name = $1;
 234 #       print STDERR "constant section '$1' = '$contents'\n";
 235         $constants{$name} = $contents;
 236     } elsif ($name =~ m/$type_param/) {
 237 #       print STDERR "parameter def '$1' = '$contents'\n";
 238         $name = $1;
 239         $parameters{$name} = $contents;
 240     } else {
 241 #       print STDERR "other section '$name' = '$contents'\n";
 242         $sections{$name} = $contents;
 243         push @sectionlist, $name;
 244     }
 245 }
 246
 247 ##
 248 # output function
 249 #
 250 # parameters, a hash.
 251 #  function => "function name"
 252 #  parameterlist => @list of parameters
 253 #  parameters => %parameter descriptions
 254 #  sectionlist => @list of sections
 255 #  sections => %descriont descriptions
 256 #
 257
 258 sub output_highlight {
 259     my $contents = join "\n", @_;
 260     my $line;
 261
 262     eval $dohighlight;
 263     $contents =~ s:CMD:@:gs if ($output_mode eq "texinfo");
 264     foreach $line (split "\n", $contents) {
 265         if ($line eq ""){
 266             print $lineprefix, $blankline;
 267         } else {
 268             print $lineprefix, $line;
 269         }
 270         print "\n";
 271     }
 272 }
 273
 274 # output in doxygen
 275 sub output_doxygen {
 276     my %args = %{$_[0]};
 277     my ($parameter, $section);
 278     my $count;
 279
 280     print "/* \\fn ";
 281     print $args{'functiontype'} . " " . $args{'function'} . " (";
 282     $count = 0;
 283     foreach $parameter (@{$args{'parameterlist'}}) {
 284         print $args{'parametertypes'}{$parameter}." ".$parameter."";
 285         if ($count != $#{$args{'parameterlist'}}) {
 286             $count++;
 287             print ", ";
 288         }
 289     }
 290     print ")\n *\n * ";
 291     foreach $parameter (@{$args{'parameterlist'}}) {
 292         if ($args{'parameters'}{$parameter}) {
 293             print "\\param ".$parameter." ";
 294             output_highlight($args{'parameters'}{$parameter});
 295             print "\n * ";
 296         }
 297     }
 298     foreach $section (@{$args{'sectionlist'}}) {
 299         output_highlight($args{'sections'}{$section});
 300         print "\n * ";
 301     }
 302     print " */\n\n";
 303 }
 304
 305 # output in texinfo
 306 sub output_texinfo {
 307     my %args = %{$_[0]};
 308     my ($parameter, $section);
 309     my $count;
 310
 311     print "\@deftypefun {";
 312     print $args{'functiontype'};
 313     print "} ".$args{'function'}." ";
 314     print "(";
 315     $count = 0;
 316     foreach $parameter (@{$args{'parameterlist'}}) {
 317         print $args{'parametertypes'}{$parameter}." \@var{".$parameter."}";
 318         if ($count != $#{$args{'parameterlist'}}) {
 319             $count++;
 320             print ", ";
 321         }
 322     }
 323     print ")\n\n";
 324     foreach $parameter (@{$args{'parameterlist'}}) {
 325         if ($args{'parameters'}{$parameter}) {
 326             print "\@var{".$parameter."}: ";
 327             output_highlight($args{'parameters'}{$parameter});
 328             print "\n";
 329         }
 330     }
 331     foreach $section (@{$args{'sectionlist'}}) {
 332         output_highlight($args{'sections'}{$section});
 333         print "\n";
 334     }
 335     print "\@end deftypefun\n\n";
 336 }
 337
 338 # output in html
 339 sub output_html {
 340     my %args = %{$_[0]};
 341     my ($parameter, $section);
 342     my $count;
 343     print "\n\n<a name=\"". $args{'function'} . "\">&nbsp</a><h2>Function</h2>\n";
 344
 345     print "<i>".$args{'functiontype'}."</i>\n";
 346     print "<b>".$args{'function'}."</b>\n";
 347     print "(";
 348     $count = 0;
 349     foreach $parameter (@{$args{'parameterlist'}}) {
 350         print "<i>".$args{'parametertypes'}{$parameter}."</i> <b>".$parameter."</b>\n";
 351         if ($count != $#{$args{'parameterlist'}}) {
 352             $count++;
 353             print ", ";
 354         }
 355     }
 356     print ")\n";
 357
 358     print "<h3>Arguments</h3>\n";
 359     print "<dl>\n";
 360     foreach $parameter (@{$args{'parameterlist'}}) {
 361         print "<dt><i>".$args{'parametertypes'}{$parameter}."</i> <b>".$parameter."</b>\n";
 362         print "<dd>";
 363         output_highlight($args{'parameters'}{$parameter});
 364     }
 365     print "</dl>\n";
 366     foreach $section (@{$args{'sectionlist'}}) {
 367         print "<h3>$section</h3>\n";
 368         print "<ul>\n";
 369         output_highlight($args{'sections'}{$section});
 370         print "</ul>\n";
 371     }
 372     print "<hr>\n";
 373 }
 374
 375 # output in tex
 376 sub output_tex {
 377     my %args = %{$_[0]};
 378     my ($parameter, $section);
 379     my $count;
 380     my $func = $args{'function'};
 381     my $param;
 382     my $param2;
 383     my $sec;
 384     my $check;
 385     my $type;
 386
 387     $func =~ s/_/\\_/g;
 388
 389     print "\n\n\\subsection{". $func . "}\n\\label{" . $args{'function'} . "}\n";
 390
 391     $type = $args{'functiontype'};
 392     $type =~ s/_/\\_/g;
 393
 394     print "{\\it ".$type."}\n";
 395     print "{\\bf ".$func."}\n";
 396     print "(\n";
 397     $count = 0;
 398     foreach $parameter (@{$args{'parameterlist'}}) {
 399         $param = $args{'parametertypes'}{$parameter};
 400         $param2 = $parameter;
 401         $param =~ s/_/\\_/g;
 402         $param2 =~ s/_/\\_/g;
 403
 404         print "{\\it ".$param."} {\\bf ".$param2."}\n";
 405         if ($count != $#{$args{'parameterlist'}}) {
 406             $count++;
 407             print ", ";
 408         }
 409     }
 410     print ")\n";
 411
 412     print "\n{\\large{Arguments}}\n";
 413
 414     print "\\begin{itemize}\n";
 415     $check=0;
 416     foreach $parameter (@{$args{'parameterlist'}}) {
 417         $param1 = $args{'parametertypes'}{$parameter};
 418         $param1 =~ s/_/\\_/g;
 419         $param2 = $parameter;
 420         $param2 =~ s/_/\\_/g;
 421
 422         $check = 1;
 423         print "\\item {\\it ".$param1."} {\\bf ".$param2."}: \n";
 424 #       print "\n";
 425
 426         $param3 = $args{'parameters'}{$parameter};
 427         $param3 =~ s/_/\\_/g;
 428         $param3 =~ s/&([a-zA-Z\_]+)/{\\it \1}/g;
 429
 430         output_highlight($param3);
 431     }
 432     if ($check==0) {
 433         print "\\item void\n";
 434     }
 435     print "\\end{itemize}\n";
 436
 437     foreach $section (@{$args{'sectionlist'}}) {
 438         $sec = $section;
 439         $sec =~ s/_/\\_/g;
 440         $sec =~ s/&([a-zA-Z\_]+)/{\\it \1}/g;
 441
 442         print "\n\\par{\\large{$sec}}\\par\n";
 443         print "\\begin{rmfamily}\n";
 444
 445         $sec = $args{'sections'}{$section};
 446         $sec =~ s/_/\\_/g;
 447         $sec =~ s/\\:/:/g;
 448         $sec =~ s/&([a-zA-Z\_]+)/{\\it \1}/g;
 449         $sec =~ s/->/\$\\rightarrow\$/g;
 450         $sec =~ s/([0-9]+)\^([0-9]+)/\$\{\1\}\^\{\2\}\$/g;
 451
 452         output_highlight($sec);
 453         print "\\end{rmfamily}\n";
 454     }
 455     print "\n";
 456 }
 457
 458
 459 # output in sgml DocBook
 460 sub output_sgml {
 461     my %args = %{$_[0]};
 462     my ($parameter, $section);
 463     my $count;
 464     my $id;
 465
 466     $id = $args{'module'}."-".$args{'function'};
 467     $id =~ s/[^A-Za-z0-9]/-/g;
 468
 469     print "<refentry>\n";
 470     print "<refmeta>\n";
 471     print "<refentrytitle><phrase id=\"$id\">".$args{'function'}."</phrase></refentrytitle>\n";
 472     print "</refmeta>\n";
 473     print "<refnamediv>\n";
 474     print " <refname>".$args{'function'}."</refname>\n";
 475     print " <refpurpose>\n";
 476     print "  ".$args{'purpose'}."\n";
 477     print " </refpurpose>\n";
 478     print "</refnamediv>\n";
 479
 480     print "<refsynopsisdiv>\n";
 481     print " <title>Synopsis</title>\n";
 482     print "  <funcsynopsis>\n";
 483     print "   <funcdef>".$args{'functiontype'}." ";
 484     print "<function>".$args{'function'}." ";
 485     print "</function></funcdef>\n";
 486
 487 #    print "<refsect1>\n";
 488 #    print " <title>Synopsis</title>\n";
 489 #    print "  <funcsynopsis>\n";
 490 #    print "   <funcdef>".$args{'functiontype'}." ";
 491 #    print "<function>".$args{'function'}." ";
 492 #    print "</function></funcdef>\n";
 493
 494     $count = 0;
 495     if ($#{$args{'parameterlist'}} >= 0) {
 496         foreach $parameter (@{$args{'parameterlist'}}) {
 497             print "   <paramdef>".$args{'parametertypes'}{$parameter};
 498             print " <parameter>$parameter</parameter></paramdef>\n";
 499         }
 500     } else {
 501         print "  <void>\n";
 502     }
 503     print "  </funcsynopsis>\n";
 504     print "</refsynopsisdiv>\n";
 505 #    print "</refsect1>\n";
 506
 507     # print parameters
 508     print "<refsect1>\n <title>Arguments</title>\n";
 509 #    print "<para>\nArguments\n";
 510     if ($#{$args{'parameterlist'}} >= 0) {
 511         print " <variablelist>\n";
 512         foreach $parameter (@{$args{'parameterlist'}}) {
 513             print "  <varlistentry>\n   <term><parameter>$parameter</parameter></term>\n";
 514             print "   <listitem>\n    <para>\n";
 515             $lineprefix="     ";
 516             output_highlight($args{'parameters'}{$parameter});
 517             print "    </para>\n   </listitem>\n  </varlistentry>\n";
 518         }
 519         print " </variablelist>\n";
 520     } else {
 521         print " <para>\n  None\n </para>\n";
 522     }
 523     print "</refsect1>\n";
 524
 525     # print out each section
 526     $lineprefix="   ";
 527     foreach $section (@{$args{'sectionlist'}}) {
 528         print "<refsect1>\n <title>$section</title>\n <para>\n";
 529 #       print "<para>\n$section\n";
 530         if ($section =~ m/EXAMPLE/i) {
 531             print "<example><para>\n";
 532         }
 533         output_highlight($args{'sections'}{$section});
 534 #       print "</para>";
 535         if ($section =~ m/EXAMPLE/i) {
 536             print "</para></example>\n";
 537         }
 538         print " </para>\n</refsect1>\n";
 539     }
 540
 541     print "\n\n";
 542 }
 543
 544 ##
 545 # output in man
 546 sub output_man {
 547     my %args = %{$_[0]};
 548     my ($parameter, $section);
 549     my $count;
 550
 551     print ".TH \"$args{'module'}\" \"$args{'function'}\" \"25 May 1998\" \"API Manual\" GNOME\n";
 552
 553     print ".SH Function\n";
 554
 555     print ".I \"".$args{'functiontype'}."\"\n";
 556     print ".B \"".$args{'function'}."\"\n";
 557     print "(\n";
 558     $count = 0;
 559     foreach $parameter (@{$args{'parameterlist'}}) {
 560         print ".I \"".$args{'parametertypes'}{$parameter}."\"\n.B \"".$parameter."\"\n";
 561         if ($count != $#{$args{'parameterlist'}}) {
 562             $count++;
 563             print ",\n";
 564         }
 565     }
 566     print ")\n";
 567
 568     print ".SH Arguments\n";
 569     foreach $parameter (@{$args{'parameterlist'}}) {
 570         print ".IP \"".$args{'parametertypes'}{$parameter}." ".$parameter."\" 12\n";
 571         output_highlight($args{'parameters'}{$parameter});
 572     }
 573     foreach $section (@{$args{'sectionlist'}}) {
 574         print ".SH \"$section\"\n";
 575         output_highlight($args{'sections'}{$section});
 576     }
 577 }
 578
 579 ##
 580 # output in text
 581 sub output_text {
 582     my %args = %{$_[0]};
 583     my ($parameter, $section);
 584
 585     print "Function = ".$args{'function'}."\n";
 586     print "  return type: ".$args{'functiontype'}."\n\n";
 587     foreach $parameter (@{$args{'parameterlist'}}) {
 588         print " ".$args{'parametertypes'}{$parameter}." ".$parameter."\n";
 589         print "    -> ".$args{'parameters'}{$parameter}."\n";
 590     }
 591     foreach $section (@{$args{'sectionlist'}}) {
 592         print " $section:\n";
 593         print "    -> ";
 594         output_highlight($args{'sections'}{$section});
 595     }
 596 }
 597
 598 ##
 599 # generic output function - calls the right one based
 600 # on current output mode.
 601 sub output_function {
 602 #    output_html(@_);
 603     eval "output_".$output_mode."(\@_);";
 604 }
 605
 606
 607 ##
 608 # takes a function prototype and spits out all the details
 609 # stored in the global arrays/hsahes.
 610 sub dump_function {
 611     my $prototype = shift @_;
 612
 613     if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ ||
 614         $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ ||
 615         $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ ||
 616         $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ ||
 617         $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/)  {
 618         $return_type = $1;
 619         $function_name = $2;
 620         $args = $3;
 621
 622 #       print STDERR "ARGS = '$args'\n";
 623
 624         foreach $arg (split ',', $args) {
 625             # strip leading/trailing spaces
 626             $arg =~ s/^\s*//;
 627             $arg =~ s/\s*$//;
 628 #           print STDERR "SCAN ARG: '$arg'\n";
 629             @args = split('\s', $arg);
 630
 631 #           print STDERR " -> @args\n";
 632             $param = pop @args;
 633 #           print STDERR " -> @args\n";
 634             if ($param =~ m/^(\*+)(.*)/) {
 635                 $param = $2;
 636                 push @args, $1;
 637             }
 638             $type = join " ", @args;
 639
 640             if ($parameters{$param} eq "" && $param != "void") {
 641                 $parameters{$param} = "-- undescribed --";
 642                 print STDERR "Warning($lineno): Function parameter '$param' not described in '$function_name'\n";
 643             }
 644
 645             push @parameterlist, $param;
 646             $parametertypes{$param} = $type;
 647
 648 #           print STDERR "param = '$param', type = '$type'\n";
 649         }
 650     } else {
 651         print STDERR "Error($lineno): cannot understand prototype: '$prototype'\n";
 652         return;
 653     }
 654
 655     if ($function_only==0 || defined($function_table{$function_name})) {
 656         output_function({'function' => $function_name,
 657                          'module' => $modulename,
 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