Annotation of embedaddon/bird2/doc/kernel-doc, revision 1.1

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

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>