doc/kernel-doc

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