doc/gdoc

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