Debian Codegraph @

doc/kernel-doc

raw
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 (sort 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 my $lbl = lc $section;
584 $lbl =~ tr/ /-/;
585 print "<sect>$section\n<label id=\"$lbl\"><p>\n";
586 output_highlight($args{'sections'}{$section});
587 }
588
589 print "\n\n";
590 }
591
592 ##
593 # output in man
594 sub output_man {
595 my %args = %{$_[0]};
596 my ($parameter, $section);
597 my $count;
598
599 print ".TH \"$args{'module'}\" \"$args{'function'}\" \"25 May 1998\" \"API Manual\" LINUX\n";
600
601 print ".SH Function\n";
602
603 print ".I \"".$args{'functiontype'}."\"\n";
604 print ".B \"".$args{'function'}."\"\n";
605 print "(\n";
606 $count = 0;
607 foreach $parameter (@{$args{'parameterlist'}}) {
608 print ".I \"".$args{'parametertypes'}{$parameter}."\"\n.B \"".$parameter."\"\n";
609 if ($count != $#{$args{'parameterlist'}}) {
610 $count++;
611 print ",\n";
612 }
613 }
614 print ")\n";
615
616 print ".SH Arguments\n";
617 foreach $parameter (@{$args{'parameterlist'}}) {
618 print ".IP \"".$args{'parametertypes'}{$parameter}." ".$parameter."\" 12\n";
619 output_highlight($args{'parameters'}{$parameter});
620 }
621 foreach $section (@{$args{'sectionlist'}}) {
622 print ".SH \"$section\"\n";
623 output_highlight($args{'sections'}{$section});
624 }
625 }
626
627 sub output_intro_man {
628 my %args = %{$_[0]};
629 my ($parameter, $section);
630 my $count;
631
632 print ".TH \"$args{'module'}\" \"$args{'module'}\" \"25 May 1998\" \"API Manual\" LINUX\n";
633
634 foreach $section (@{$args{'sectionlist'}}) {
635 print ".SH \"$section\"\n";
636 output_highlight($args{'sections'}{$section});
637 }
638 }
639
640 ##
641 # output in text
642 sub output_text {
643 my %args = %{$_[0]};
644 my ($parameter, $section);
645
646 print "Function = ".$args{'function'}."\n";
647 print " return type: ".$args{'functiontype'}."\n\n";
648 foreach $parameter (@{$args{'parameterlist'}}) {
649 print " ".$args{'parametertypes'}{$parameter}." ".$parameter."\n";
650 print " -> ".$args{'parameters'}{$parameter}."\n";
651 }
652 foreach $section (@{$args{'sectionlist'}}) {
653 print " $section:\n";
654 print " -> ";
655 output_highlight($args{'sections'}{$section});
656 }
657 }
658
659 sub output_intro_text {
660 my %args = %{$_[0]};
661 my ($parameter, $section);
662
663 foreach $section (@{$args{'sectionlist'}}) {
664 print " $section:\n";
665 print " -> ";
666 output_highlight($args{'sections'}{$section});
667 }
668 }
669
670 ##
671 # generic output function - calls the right one based
672 # on current output mode.
673 sub output_function {
674 # output_html(@_);
675 eval "output_".$output_mode."(\@_);";
676 }
677
678 ##
679 # generic output function - calls the right one based
680 # on current output mode.
681 sub output_intro {
682 # output_html(@_);
683 eval "output_intro_".$output_mode."(\@_);";
684 }
685
686
687 ##
688 # takes a function prototype and spits out all the details
689 # stored in the global arrays/hsahes.
690 sub dump_function {
691 my $prototype = shift @_;
692
693 $prototype =~ s/^static+ //;
694 $prototype =~ s/^extern+ //;
695 $prototype =~ s/^inline+ //;
696 $prototype =~ s/^__inline__+ //;
697
698 if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ ||
699 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ ||
700 $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ ||
701 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ ||
702 $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/) {
703 $return_type = $1;
704 $function_name = $2;
705 $args = $3;
706
707 # print STDERR "ARGS = '$args'\n";
708
709 foreach $arg (split ',', $args) {
710 # strip leading/trailing spaces
711 $arg =~ s/^\s*//;
712 $arg =~ s/\s*$//;
713 # print STDERR "SCAN ARG: '$arg'\n";
714 @args = split('\s', $arg);
715
716 # print STDERR " -> @args\n";
717 $param = pop @args;
718 # print STDERR " -> @args\n";
719 if ($param =~ m/^(\*+)(.*)/) {
720 $param = $2;
721 push @args, $1;
722 }
723 $type = join " ", @args;
724
725 if ($type eq "" && $param eq "...")
726 {
727 $type="...";
728 $param="...";
729 $parameters{"..."} = "variable arguments";
730 }
731 if ($type eq "")
732 {
733 $type="";
734 $param="void";
735 $parameters{void} = "no arguments";
736 }
737 if ($parameters{$param} eq "") {
738 $parameters{$param} = "-- undescribed --";
739 print STDERR "Warning($lineno): Function parameter '$param' not described in '$function_name'\n";
740 }
741
742 push @parameterlist, $param;
743 $parametertypes{$param} = $type;
744 # print STDERR "param = '$param', type = '$type'\n";
745 }
746 } else {
747 print STDERR "Error($lineno): cannot understand prototype: '$prototype'\n";
748 return;
749 }
750
751 if ($function_only==0 ||
752 ( $function_only == 1 && defined($function_table{$function_name})) ||
753 ( $function_only == 2 && !defined($function_table{$function_name})))
754 {
755 output_function({'function' => $function_name,
756 'module' => $modulename,
757 'functiontype' => $return_type,
758 'parameterlist' => \@parameterlist,
759 'parameters' => \%parameters,
760 'parametertypes' => \%parametertypes,
761 'sectionlist' => \@sectionlist,
762 'sections' => \%sections,
763 'purpose' => $function_purpose
764 });
765 }
766 }
767
768 ######################################################################
769 # main
770 # states
771 # 0 - normal code
772 # 1 - looking for function name
773 # 2 - scanning field start.
774 # 3 - scanning prototype.
775 $state = 0;
776 $section = "";
777
778 $doc_special = "\@\%\$\&";
779
780 $doc_start = "^/\\*\\*\$";
781 $doc_end = "\\*/";
782 $doc_com = "\\s*\\*\\s*";
783 $doc_func = $doc_com."(\\w+):?";
784 $doc_sect = $doc_com."([".$doc_special."]?[\\w ]+):(.*)";
785 $doc_content = $doc_com."(.*)";
786 $doc_block = $doc_com."DOC:\\s*(.*)?";
787
788 %constants = ();
789 %parameters = ();
790 @parameterlist = ();
791 %sections = ();
792 @sectionlist = ();
793
794 $contents = "";
795 $section_default = "Description"; # default section
796 $section_intro = "Introduction";
797 $section = $section_default;
798
799 $lineno = 0;
800 foreach $file (@ARGV) {
801 if (!open(IN,"<$file")) {
802 print STDERR "Error: Cannot open file $file\n";
803 next;
804 }
805 while (<IN>) {
806 $lineno++;
807
808 if ($state == 0) {
809 if (/$doc_start/o) {
810 $state = 1; # next line is always the function name
811 }
812 } elsif ($state == 1) { # this line is the function name (always)
813 if (/$doc_block/o) {
814 $state = 4;
815 $contents = "";
816 if ( $1 eq "" ) {
817 $section = $section_intro;
818 } else {
819 $section = $1;
820 }
821 }
822 elsif (/$doc_func/o) {
823 $function = $1;
824 $state = 2;
825 if (/-(.*)/) {
826 $function_purpose = $1;
827 } else {
828 $function_purpose = "";
829 }
830 if ($verbose) {
831 print STDERR "Info($lineno): Scanning doc for $function\n";
832 }
833 } else {
834 print STDERR "WARN($lineno): Cannot understand $_ on line $lineno",
835 " - I thought it was a doc line\n";
836 $state = 0;
837 }
838 } elsif ($state == 2) { # look for head: lines, and include content
839 if (/$doc_sect/o) {
840 $newsection = $1;
841 $newcontents = $2;
842
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;
849 }
850
851 $contents = $newcontents;
852 if ($contents ne "") {
853 $contents .= "\n";
854 }
855 $section = $newsection;
856 } elsif (/$doc_end/) {
857
858 if ($contents ne "") {
859 # $contents =~ s/\&/\\\\\\amp;/g;
860 $contents =~ s/\</\\\\\\lt;/g;
861 $contents =~ s/\>/\\\\\\gt;/g;
862 dump_section($section, $contents);
863 $section = $section_default;
864 $contents = "";
865 }
866
867 # print STDERR "end of doc comment, looking for prototype\n";
868 $prototype = "";
869 $state = 3;
870 } elsif (/$doc_content/) {
871 # miguel-style comment kludge, look for blank lines after
872 # @parameter line to signify start of description
873 if ($1 eq "" && $section =~ m/^@/) {
874 # $contents =~ s/\&/\\\\\\amp;/g;
875 $contents =~ s/\</\\\\\\lt;/g;
876 $contents =~ s/\>/\\\\\\gt;/g;
877 dump_section($section, $contents);
878 $section = $section_default;
879 $contents = "";
880 } else {
881 $contents .= $1."\n";
882 }
883 } else {
884 # i dont know - bad line? ignore.
885 print STDERR "WARNING($lineno): bad line: $_";
886 }
887 } elsif ($state == 3) { # scanning for function { (end of prototype)
888 if (m#\s*/\*\s+MACDOC\s*#io) {
889 # do nothing
890 }
891 elsif (/([^\{]*)/) {
892 $prototype .= $1;
893 }
894 if (/\{/) {
895 $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
896 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
897 $prototype =~ s@^ +@@gos; # strip leading spaces
898 dump_function($prototype);
899
900 $function = "";
901 %constants = ();
902 %parameters = ();
903 %parametertypes = ();
904 @parameterlist = ();
905 %sections = ();
906 @sectionlist = ();
907 $prototype = "";
908
909 $state = 0;
910 }
911 } elsif ($state == 4) {
912 # Documentation block
913 if (/$doc_block/) {
914 # $contents =~ s/\&/\\\\\\amp;/g;
915 $contents =~ s/\</\\\\\\lt;/g;
916 $contents =~ s/\>/\\\\\\gt;/g;
917 dump_section($section, $contents);
918 output_intro({'sectionlist' => \@sectionlist,
919 'sections' => \%sections });
920 $contents = "";
921 $function = "";
922 %constants = ();
923 %parameters = ();
924 %parametertypes = ();
925 @parameterlist = ();
926 %sections = ();
927 @sectionlist = ();
928 $prototype = "";
929 if ( $1 eq "" ) {
930 $section = $section_intro;
931 } else {
932 $section = $1;
933 }
934 }
935 elsif (/$doc_end/)
936 {
937 # $contents =~ s/\&/\\\\\\amp;/g;
938 $contents =~ s/\</\\\\\\lt;/g;
939 $contents =~ s/\>/\\\\\\gt;/g;
940 dump_section($section, $contents);
941 output_intro({'sectionlist' => \@sectionlist,
942 'sections' => \%sections });
943 $contents = "";
944 $function = "";
945 %constants = ();
946 %parameters = ();
947 %parametertypes = ();
948 @parameterlist = ();
949 %sections = ();
950 @sectionlist = ();
951 $prototype = "";
952 $state = 0;
953 }
954 elsif (/$doc_content/)
955 {
956 if ( $1 eq "" )
957 {
958 $contents .= "\n";
959 }
960 else
961 {
962 $contents .= $1 . "\n";
963 }
964 }
965 }
966 }
967 }
968