3 ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
4 ## Copyright (C) 2000 Tim Waugh <twaugh@redhat.com> ##
6 ## This software falls under the GNU General Public License. ##
7 ## Please read the COPYING file for more information ##
10 # This will read a 'c' file and scan for embedded comments in the
11 # style of gnome comments (+minor extensions - see below).
14 # Note: This only supports 'c'.
17 # kerneldoc [ -docbook | -html | -text | -man ]
18 # [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
20 # [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile
22 # Set output format using one of -docbook -html -text or -man. Default is man.
25 # If set, then only generate documentation for the given function(s). All
26 # other functions are ignored.
28 # -nofunction funcname
29 # If set, then only generate documentation for the other function(s). All
30 # other functions are ignored. Cannot be used with -function together
31 # (yes thats a bug - perl hackers can fix it 8))
33 # c files - list of 'c' files to process
35 # All output goes to stdout, with errors to stderr.
39 # In the following table, (...)? signifies optional structure.
40 # (...)* signifies 0 or more structure elements
42 # * function_name(:)? (- short description)?
43 # (* @parameterx: (description of parameter x)?)*
45 # * (Description:)? (Description of function)?
46 # * (section header: (section description)? )*
49 # So .. the trivial example would be:
55 # If the Description: header tag is ommitted, then there must be a blank line
56 # after the last parameter specification.
59 # * my_function - does my stuff
60 # * @my_arg: its mine damnit
62 # * Does my stuff explained.
67 # * my_function - does my stuff
68 # * @my_arg: its mine damnit
69 # * Description: Does my stuff explained.
73 # All descriptions can be multiline, apart from the short function description.
75 # All descriptive text is further processed, scanning for the following special
76 # patterns, which are highlighted appropriately.
78 # 'funcname()' - function
79 # '$ENVVAR' - environmental variable
80 # '&struct_name' - name of a structure (up to two words including 'struct')
81 # '@parameter' - name of a parameter
82 # '%CONST' - name of a constant.
84 # match expressions used to find embedded type information
85 $type_constant = "\\\%([-_\\w]+)";
86 $type_func = "(\\w+)\\(\\)";
87 $type_param = "\\\@(\\w+)";
88 $type_struct = "\\\&((struct\\s*)?\\w+)";
89 $type_env = "(\\\$\\w+)";
92 # Output conversion substitutions.
93 # One for each output format
95 # these work fairly well
96 %highlights_html = ( $type_constant, "<i>\$1</i>",
97 $type_func, "<b>\$1</b>",
98 $type_struct, "<i>\$1</i>",
99 $type_param, "<tt><b>\$1</b></tt>" );
100 $blankline_html = "<p>";
102 # sgml, docbook format
103 %highlights_sgml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
104 $type_constant, "<constant>\$1</constant>",
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";
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";
119 # these are pretty rough
120 %highlights_man = ( $type_constant, "\$1",
121 $type_func, "\\\\fB\$1\\\\fP",
122 $type_struct, "\\\\fI\$1\\\\fP",
123 $type_param, "\\\\fI\$1\\\\fP" );
127 %highlights_text = ( $type_constant, "\$1",
130 $type_param, "\$1" );
131 $blankline_text = "";
135 print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ]\n";
136 print " [ -function funcname [ -function funcname ...] ]\n";
137 print " [ -nofunction funcname [ -nofunction funcname ...] ]\n";
138 print " c source file(s) > outputfile\n";
148 $output_mode = "man";
149 %highlights = %highlights_man;
150 $blankline = $blankline_man;
151 $modulename = "API Documentation";
153 while ($ARGV[0] =~ m/^-(.*)/) {
155 if ($cmd eq "-html") {
156 $output_mode = "html";
157 %highlights = %highlights_html;
158 $blankline = $blankline_html;
159 } elsif ($cmd eq "-man") {
160 $output_mode = "man";
161 %highlights = %highlights_man;
162 $blankline = $blankline_man;
163 } elsif ($cmd eq "-text") {
164 $output_mode = "text";
165 %highlights = %highlights_text;
166 $blankline = $blankline_text;
167 } elsif ($cmd eq "-docbook") {
168 $output_mode = "sgml";
169 %highlights = %highlights_sgml;
170 $blankline = $blankline_sgml;
171 } elsif ($cmd eq "-gnome") {
172 $output_mode = "gnome";
173 %highlights = %highlights_gnome;
174 $blankline = $blankline_gnome;
175 } elsif ($cmd eq "-module") { # not needed for sgml, inherits from calling document
176 $modulename = shift @ARGV;
177 } elsif ($cmd eq "-function") { # to only output specific functions
179 $function = shift @ARGV;
180 $function_table{$function} = 1;
181 } elsif ($cmd eq "-nofunction") { # to only output specific functions
183 $function = shift @ARGV;
184 $function_table{$function} = 1;
185 } elsif ($cmd eq "-v") {
187 } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
193 # generate a sequence of code that will splice in highlighting information
194 # using the s// operator.
196 foreach $pattern (keys %highlights) {
197 # print "scanning pattern $pattern ($highlights{$pattern})\n";
198 $dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
202 # dumps section contents to arrays/hashes intended for that purpose.
206 my $contents = join "\n", @_;
208 if ($name =~ m/$type_constant/) {
210 # print STDERR "constant section '$1' = '$contents'\n";
211 $constants{$name} = $contents;
212 } elsif ($name =~ m/$type_param/) {
213 # print STDERR "parameter def '$1' = '$contents'\n";
215 $parameters{$name} = $contents;
217 # print STDERR "other section '$name' = '$contents'\n";
218 $sections{$name} = $contents;
219 push @sectionlist, $name;
226 # parameters, a hash.
227 # function => "function name"
228 # parameterlist => @list of parameters
229 # parameters => %parameter descriptions
230 # sectionlist => @list of sections
231 # sections => %descriont descriptions
234 sub output_highlight
{
235 my $contents = join "\n", @_;
239 foreach $line (split "\n", $contents) {
241 print $lineprefix, $blankline;
243 $line =~ s/\\\\\\/\&/g;
244 print $lineprefix, $line;
254 my ($parameter, $section);
256 print "<h2>Function</h2>\n";
258 print "<i>".$args{'functiontype'}."</i>\n";
259 print "<b>".$args{'function'}."</b>\n";
262 foreach $parameter (@
{$args{'parameterlist'}}) {
263 $type = $args{'parametertypes'}{$parameter};
264 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
265 # pointer-to-function
266 print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
268 print "<i>".$type."</i> <b>".$parameter."</b>";
270 if ($count != $#{$args{'parameterlist'}}) {
277 print "<h3>Arguments</h3>\n";
279 foreach $parameter (@
{$args{'parameterlist'}}) {
280 print "<dt><b>".$parameter."</b>\n";
282 output_highlight
($args{'parameters'}{$parameter});
285 foreach $section (@
{$args{'sectionlist'}}) {
286 print "<h3>$section</h3>\n";
287 print "<blockquote>\n";
288 output_highlight
($args{'sections'}{$section});
289 print "</blockquote>\n";
296 sub output_intro_html
{
298 my ($parameter, $section);
301 foreach $section (@
{$args{'sectionlist'}}) {
302 print "<h3>$section</h3>\n";
304 output_highlight
($args{'sections'}{$section});
312 # output in sgml DocBook
315 my ($parameter, $section);
319 $id = "API-".$args{'function'};
320 $id =~ s/[^A-Za-z0-9]/-/g;
322 print "<refentry>\n";
324 print "<refentrytitle><phrase id=\"$id\">".$args{'function'}."</phrase></refentrytitle>\n";
325 print "</refmeta>\n";
326 print "<refnamediv>\n";
327 print " <refname>".$args{'function'}."</refname>\n";
328 print " <refpurpose>\n";
329 print " ".$args{'purpose'}."\n";
330 print " </refpurpose>\n";
331 print "</refnamediv>\n";
333 print "<refsynopsisdiv>\n";
334 print " <title>Synopsis</title>\n";
335 print " <funcsynopsis>\n";
336 print " <funcdef>".$args{'functiontype'}." ";
337 print "<function>".$args{'function'}." ";
338 print "</function></funcdef>\n";
340 # print "<refsect1>\n";
341 # print " <title>Synopsis</title>\n";
342 # print " <funcsynopsis>\n";
343 # print " <funcdef>".$args{'functiontype'}." ";
344 # print "<function>".$args{'function'}." ";
345 # print "</function></funcdef>\n";
348 if ($#{$args{'parameterlist'}} >= 0) {
349 foreach $parameter (@
{$args{'parameterlist'}}) {
350 $type = $args{'parametertypes'}{$parameter};
351 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
352 # pointer-to-function
353 print " <paramdef>$1<parameter>$parameter</parameter>)\n";
354 print " <funcparams>$2</funcparams></paramdef>\n";
356 print " <paramdef>".$type;
357 print " <parameter>$parameter</parameter></paramdef>\n";
363 print " </funcsynopsis>\n";
364 print "</refsynopsisdiv>\n";
365 # print "</refsect1>\n";
368 print "<refsect1>\n <title>Arguments</title>\n";
369 # print "<para>\nArguments\n";
370 if ($#{$args{'parameterlist'}} >= 0) {
371 print " <variablelist>\n";
372 foreach $parameter (@
{$args{'parameterlist'}}) {
373 print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n";
374 print " <listitem>\n <para>\n";
376 output_highlight
($args{'parameters'}{$parameter});
377 print " </para>\n </listitem>\n </varlistentry>\n";
379 print " </variablelist>\n";
381 print " <para>\n None\n </para>\n";
383 print "</refsect1>\n";
385 # print out each section
387 foreach $section (@
{$args{'sectionlist'}}) {
388 print "<refsect1>\n <title>$section</title>\n <para>\n";
389 # print "<para>\n$section\n";
390 if ($section =~ m/EXAMPLE/i) {
391 print "<example><para>\n";
393 output_highlight
($args{'sections'}{$section});
395 if ($section =~ m/EXAMPLE/i) {
396 print "</para></example>\n";
398 print " </para>\n</refsect1>\n";
401 print "</refentry>\n\n";
404 # output in sgml DocBook
405 sub output_intro_sgml
{
407 my ($parameter, $section);
411 $id = $args{'module'};
412 $id =~ s/[^A-Za-z0-9]/-/g;
414 # print out each section
416 foreach $section (@
{$args{'sectionlist'}}) {
417 print "<refsect1>\n <title>$section</title>\n <para>\n";
418 # print "<para>\n$section\n";
419 if ($section =~ m/EXAMPLE/i) {
420 print "<example><para>\n";
422 output_highlight
($args{'sections'}{$section});
424 if ($section =~ m/EXAMPLE/i) {
425 print "</para></example>\n";
427 print " </para>\n</refsect1>\n";
433 # output in sgml DocBook
436 my ($parameter, $section);
440 $id = $args{'module'}."-".$args{'function'};
441 $id =~ s/[^A-Za-z0-9]/-/g;
444 print " <title id=\"$id\">".$args{'function'}."</title>\n";
446 # print "<simplesect>\n";
447 # print " <title>Synopsis</title>\n";
448 print " <funcsynopsis>\n";
449 print " <funcdef>".$args{'functiontype'}." ";
450 print "<function>".$args{'function'}." ";
451 print "</function></funcdef>\n";
454 if ($#{$args{'parameterlist'}} >= 0) {
455 foreach $parameter (@
{$args{'parameterlist'}}) {
456 $type = $args{'parametertypes'}{$parameter};
457 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
458 # pointer-to-function
459 print " <paramdef>$1 <parameter>$parameter</parameter>)\n";
460 print " <funcparams>$2</funcparams></paramdef>\n";
462 print " <paramdef>".$type;
463 print " <parameter>$parameter</parameter></paramdef>\n";
469 print " </funcsynopsis>\n";
470 # print "</simplesect>\n";
471 # print "</refsect1>\n";
474 # print "<simplesect>\n <title>Arguments</title>\n";
475 # if ($#{$args{'parameterlist'}} >= 0) {
476 # print " <variablelist>\n";
477 # foreach $parameter (@{$args{'parameterlist'}}) {
478 # print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n";
479 # print " <listitem>\n <para>\n";
481 # output_highlight($args{'parameters'}{$parameter});
482 # print " </para>\n </listitem>\n </varlistentry>\n";
484 # print " </variablelist>\n";
486 # print " <para>\n None\n </para>\n";
488 # print "</simplesect>\n";
490 # print "<simplesect>\n <title>Arguments</title>\n";
491 if ($#{$args{'parameterlist'}} >= 0) {
492 print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
493 print "<tgroup cols=\"2\">\n";
494 print "<colspec colwidth=\"2*\">\n";
495 print "<colspec colwidth=\"8*\">\n";
497 foreach $parameter (@
{$args{'parameterlist'}}) {
498 print " <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
501 output_highlight
($args{'parameters'}{$parameter});
502 print " </entry></row>\n";
504 print " </tbody></tgroup></informaltable>\n";
506 print " <para>\n None\n </para>\n";
508 # print "</simplesect>\n";
510 # print out each section
512 foreach $section (@
{$args{'sectionlist'}}) {
513 print "<simplesect>\n <title>$section</title>\n";
514 # print "<para>\n$section\n";
515 if ($section =~ m/EXAMPLE/i) {
516 print "<example><programlisting>\n";
520 output_highlight
($args{'sections'}{$section});
523 if ($section =~ m/EXAMPLE/i) {
524 print "</programlisting></example>\n";
527 print " </simplesect>\n";
530 print "</sect2>\n\n";
537 my ($parameter, $section);
540 print ".TH \"$args{'module'}\" 4 \"$args{'function'}\" \"25 May 1998\" \"API Manual\" LINUX\n";
543 print $args{'function'}." \\- ".$args{'purpose'}."\n";
545 print ".SH SYNOPSIS\n";
546 print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n";
550 foreach $parameter (@
{$args{'parameterlist'}}) {
551 if ($count == $#{$args{'parameterlist'}}) {
554 $type = $args{'parametertypes'}{$parameter};
555 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
556 # pointer-to-function
557 print ".BI \"".$parenth.$1."\" ".$parameter." \") (".$2.")".$post."\"\n";
559 $type =~ s/([^\*])$/\1 /;
560 print ".BI \"".$parenth.$type."\" ".$parameter." \"".$post."\"\n";
566 print ".SH Arguments\n";
567 foreach $parameter (@
{$args{'parameterlist'}}) {
568 print ".IP \"".$parameter."\" 12\n";
569 output_highlight
($args{'parameters'}{$parameter});
571 foreach $section (@
{$args{'sectionlist'}}) {
572 print ".SH \"$section\"\n";
573 output_highlight
($args{'sections'}{$section});
577 sub output_intro_man
{
579 my ($parameter, $section);
582 print ".TH \"$args{'module'}\" 4 \"$args{'module'}\" \"25 May 1998\" \"API Manual\" LINUX\n";
584 foreach $section (@
{$args{'sectionlist'}}) {
585 print ".SH \"$section\"\n";
586 output_highlight
($args{'sections'}{$section});
594 my ($parameter, $section);
596 print "Function:\n\n";
597 $start=$args{'functiontype'}." ".$args{'function'}." (";
600 foreach $parameter (@
{$args{'parameterlist'}}) {
601 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
602 # pointer-to-function
603 print $1.$parameter.") (".$2;
605 print $type." ".$parameter;
607 if ($count != $#{$args{'parameterlist'}}) {
610 print " " x
length($start);
616 print "Arguments:\n\n";
617 foreach $parameter (@
{$args{'parameterlist'}}) {
618 print $parameter."\n\t".$args{'parameters'}{$parameter}."\n";
620 foreach $section (@
{$args{'sectionlist'}}) {
621 print "$section:\n\n";
622 output_highlight
($args{'sections'}{$section});
627 sub output_intro_text
{
629 my ($parameter, $section);
631 foreach $section (@
{$args{'sectionlist'}}) {
632 print " $section:\n";
634 output_highlight
($args{'sections'}{$section});
639 # generic output function - calls the right one based
640 # on current output mode.
641 sub output_function
{
643 eval "output_".$output_mode."(\@_);";
647 # generic output function - calls the right one based
648 # on current output mode.
651 eval "output_intro_".$output_mode."(\@_);";
656 # takes a function prototype and spits out all the details
657 # stored in the global arrays/hsahes.
659 my $prototype = shift @_;
661 $prototype =~ s/^static+ //;
662 $prototype =~ s/^extern+ //;
663 $prototype =~ s/^inline+ //;
664 $prototype =~ s/^__inline__+ //;
666 if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
667 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
668 $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
669 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
670 $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) {
675 # allow for up to fours args to function pointers
676 $args =~ s/(\([^\),]+),/\1#/g;
677 $args =~ s/(\([^\),]+),/\1#/g;
678 $args =~ s/(\([^\),]+),/\1#/g;
679 # print STDERR "ARGS = '$args'\n";
681 foreach $arg (split ',', $args) {
682 # strip leading/trailing spaces
687 # pointer-to-function
689 $arg =~ m/[^\(]+\(\*([^\)]+)\)/;
692 $type =~ s/([^\(]+\(\*)$param/\1/;
694 # evil magic to get fixed array parameters to work
695 $arg =~ s/(.+\s+)(.+)\[.*/\1* \2/;
696 # print STDERR "SCAN ARG: '$arg'\n";
697 @args = split('\s', $arg);
699 # print STDERR " -> @args\n";
701 # print STDERR " -> @args\n";
702 if ($param =~ m/^(\*+)(.*)/) {
706 $type = join " ", @args;
709 if ($type eq "" && $param eq "...")
713 $parameters{"..."} = "variable arguments";
719 $parameters{void
} = "no arguments";
721 if ($parameters{$param} eq "") {
722 $parameters{$param} = "-- undescribed --";
723 print STDERR
"Warning($file:$lineno): Function parameter '$param' not described in '$function_name'\n";
726 push @parameterlist, $param;
727 $parametertypes{$param} = $type;
728 # print STDERR "param = '$param', type = '$type'\n";
731 print STDERR
"Error($lineno): cannot understand prototype: '$prototype'\n";
735 if ($function_only==0 ||
736 ( $function_only == 1 && defined($function_table{$function_name})) ||
737 ( $function_only == 2 && !defined($function_table{$function_name})))
739 output_function
({'function' => $function_name,
740 'module' => $modulename,
741 'functiontype' => $return_type,
742 'parameterlist' => \
@parameterlist,
743 'parameters' => \
%parameters,
744 'parametertypes' => \
%parametertypes,
745 'sectionlist' => \
@sectionlist,
746 'sections' => \
%sections,
747 'purpose' => $function_purpose
752 ######################################################################
756 # 1 - looking for function name
757 # 2 - scanning field start.
758 # 3 - scanning prototype.
762 $doc_special = "\@\%\$\&";
764 $doc_start = "^/\\*\\*\$";
766 $doc_com = "\\s*\\*\\s*";
767 $doc_func = $doc_com."(\\w+):?";
768 $doc_sect = $doc_com."([".$doc_special."]?[\\w ]+):(.*)";
769 $doc_content = $doc_com."(.*)";
770 $doc_block = $doc_com."DOC:\\s*(.*)?";
779 $section_default = "Description"; # default section
780 $section_intro = "Introduction";
781 $section = $section_default;
784 foreach $file (@ARGV) {
786 if (!open(IN
,"<$file")) {
787 print STDERR
"Error: Cannot open file $file\n";
795 $state = 1; # next line is always the function name
797 } elsif ($state == 1) { # this line is the function name (always)
802 $section = $section_intro;
807 elsif (/$doc_func/o) {
811 $function_purpose = $1;
813 $function_purpose = "";
816 print STDERR
"Info($lineno): Scanning doc for $function\n";
819 print STDERR
"WARN($lineno): Cannot understand $_ on line $lineno",
820 " - I thought it was a doc line\n";
823 } elsif ($state == 2) { # look for head: lines, and include content
828 if ($contents ne "") {
829 $contents =~ s/\&/\\\\\\amp;/g;
830 $contents =~ s/\</\\\\\\lt;/g;
831 $contents =~ s/\>/\\\\\\gt;/g;
832 dump_section
($section, $contents);
833 $section = $section_default;
836 $contents = $newcontents;
837 if ($contents ne "") {
840 $section = $newsection;
841 } elsif (/$doc_end/) {
843 if ($contents ne "") {
844 $contents =~ s/\&/\\\\\\amp;/g;
845 $contents =~ s/\</\\\\\\lt;/g;
846 $contents =~ s/\>/\\\\\\gt;/g;
847 dump_section
($section, $contents);
848 $section = $section_default;
852 # print STDERR "end of doc comment, looking for prototype\n";
855 } elsif (/$doc_content/) {
856 # miguel-style comment kludge, look for blank lines after
857 # @parameter line to signify start of description
858 if ($1 eq "" && $section =~ m/^@/) {
859 $contents =~ s/\&/\\\\\\amp;/g;
860 $contents =~ s/\</\\\\\\lt;/g;
861 $contents =~ s/\>/\\\\\\gt;/g;
862 dump_section
($section, $contents);
863 $section = $section_default;
866 $contents .= $1."\n";
869 # i dont know - bad line? ignore.
870 print STDERR
"WARNING($lineno): bad line: $_";
872 } elsif ($state == 3) { # scanning for function { (end of prototype)
873 if (m
#\s*/\*\s+MACDOC\s*#io) {
880 $prototype =~ s@
/\*.*?\*/@
@gos; # strip comments.
881 $prototype =~ s@
[\r\n]+@
@gos; # strip newlines/cr's.
882 $prototype =~ s@
^ +@
@gos; # strip leading spaces
883 dump_function
($prototype);
888 %parametertypes = ();
896 } elsif ($state == 4) {
897 # Documentation block
899 dump_section
($section, $contents);
900 output_intro
({'sectionlist' => \
@sectionlist,
901 'sections' => \
%sections });
906 %parametertypes = ();
912 $section = $section_intro;
919 dump_section
($section, $contents);
920 output_intro
({'sectionlist' => \
@sectionlist,
921 'sections' => \
%sections });
926 %parametertypes = ();
933 elsif (/$doc_content/)
937 $contents .= $blankline;
941 $contents .= $1 . "\n";