Annotation of embedaddon/bird/doc/kernel-doc, revision 1.1.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>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to kernel-doc CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / bird / doc