]>
Commit | Line | Data |
---|---|---|
be67fdd0 | 1 | #!/usr/bin/perl |
2 | ||
3 | ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ## | |
4 | ## Copyright (C) 2000 Tim Waugh <twaugh@redhat.com> ## | |
5 | ## ## | |
6 | ## This software falls under the GNU General Public License. ## | |
7 | ## Please read the COPYING file for more information ## | |
8 | ||
9 | # | |
10 | # This will read a 'c' file and scan for embedded comments in the | |
11 | # style of gnome comments (+minor extensions - see below). | |
12 | # | |
13 | ||
14 | # Note: This only supports 'c'. | |
15 | ||
16 | # usage: | |
17 | # kerneldoc [ -docbook | -html | -text | -man ] | |
18 | # [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile | |
19 | # or | |
20 | # [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile | |
21 | # | |
22 | # Set output format using one of -docbook -html -text or -man. Default is man. | |
23 | # | |
24 | # -function funcname | |
25 | # If set, then only generate documentation for the given function(s). All | |
26 | # other functions are ignored. | |
27 | # | |
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)) | |
32 | # | |
33 | # c files - list of 'c' files to process | |
34 | # | |
35 | # All output goes to stdout, with errors to stderr. | |
36 | ||
37 | # | |
38 | # format of comments. | |
39 | # In the following table, (...)? signifies optional structure. | |
40 | # (...)* signifies 0 or more structure elements | |
41 | # /** | |
42 | # * function_name(:)? (- short description)? | |
43 | # (* @parameterx: (description of parameter x)?)* | |
44 | # (* a blank line)? | |
45 | # * (Description:)? (Description of function)? | |
46 | # * (section header: (section description)? )* | |
47 | # (*)?*/ | |
48 | # | |
49 | # So .. the trivial example would be: | |
50 | # | |
51 | # /** | |
52 | # * my_function | |
53 | # **/ | |
54 | # | |
55 | # If the Description: header tag is ommitted, then there must be a blank line | |
56 | # after the last parameter specification. | |
57 | # e.g. | |
58 | # /** | |
59 | # * my_function - does my stuff | |
60 | # * @my_arg: its mine damnit | |
61 | # * | |
62 | # * Does my stuff explained. | |
63 | # */ | |
64 | # | |
65 | # or, could also use: | |
66 | # /** | |
67 | # * my_function - does my stuff | |
68 | # * @my_arg: its mine damnit | |
69 | # * Description: Does my stuff explained. | |
70 | # */ | |
71 | # etc. | |
72 | # | |
73 | # All descriptions can be multiline, apart from the short function description. | |
74 | # | |
75 | # All descriptive text is further processed, scanning for the following special | |
76 | # patterns, which are highlighted appropriately. | |
77 | # | |
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. | |
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 = "\\\&((struct\\s*)?\\w+)"; | |
89 | $type_env = "(\\\$\\w+)"; | |
90 | ||
91 | ||
92 | # Output conversion substitutions. | |
93 | # One for each output format | |
94 | ||
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>"; | |
101 | ||
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"; | |
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 | # 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" ); | |
124 | $blankline_man = ""; | |
125 | ||
126 | # text-mode | |
127 | %highlights_text = ( $type_constant, "\$1", | |
128 | $type_func, "\$1", | |
129 | $type_struct, "\$1", | |
130 | $type_param, "\$1" ); | |
131 | $blankline_text = ""; | |
132 | ||
133 | ||
134 | sub usage { | |
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"; | |
139 | exit 1; | |
140 | } | |
141 | ||
142 | # read arguments | |
143 | if ($#ARGV==-1) { | |
144 | usage(); | |
145 | } | |
146 | ||
147 | $verbose = 0; | |
148 | $output_mode = "man"; | |
149 | %highlights = %highlights_man; | |
150 | $blankline = $blankline_man; | |
151 | $modulename = "libfaim API Documentation"; | |
152 | $function_only = 0; | |
153 | while ($ARGV[0] =~ m/^-(.*)/) { | |
154 | $cmd = shift @ARGV; | |
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 | |
178 | $function_only = 1; | |
179 | $function = shift @ARGV; | |
180 | $function_table{$function} = 1; | |
181 | } elsif ($cmd eq "-nofunction") { # to only output specific functions | |
182 | $function_only = 2; | |
183 | $function = shift @ARGV; | |
184 | $function_table{$function} = 1; | |
185 | } elsif ($cmd eq "-v") { | |
186 | $verbose = 1; | |
187 | } elsif (($cmd eq "-h") || ($cmd eq "--help")) { | |
188 | usage(); | |
189 | } | |
190 | } | |
191 | ||
192 | ||
193 | # generate a sequence of code that will splice in highlighting information | |
194 | # using the s// operator. | |
195 | $dohighlight = ""; | |
196 | foreach $pattern (keys %highlights) { | |
197 | # print "scanning pattern $pattern ($highlights{$pattern})\n"; | |
198 | $dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n"; | |
199 | } | |
200 | ||
201 | ## | |
202 | # dumps section contents to arrays/hashes intended for that purpose. | |
203 | # | |
204 | sub dump_section { | |
205 | my $name = shift @_; | |
206 | my $contents = join "\n", @_; | |
207 | ||
208 | if ($name =~ m/$type_constant/) { | |
209 | $name = $1; | |
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"; | |
214 | $name = $1; | |
215 | $parameters{$name} = $contents; | |
216 | } else { | |
217 | # print STDERR "other section '$name' = '$contents'\n"; | |
218 | $sections{$name} = $contents; | |
219 | push @sectionlist, $name; | |
220 | } | |
221 | } | |
222 | ||
223 | ## | |
224 | # output function | |
225 | # | |
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 | |
232 | # | |
233 | ||
234 | sub output_highlight { | |
235 | my $contents = join "\n", @_; | |
236 | my $line; | |
237 | ||
238 | eval $dohighlight; | |
239 | foreach $line (split "\n", $contents) { | |
240 | if ($line eq ""){ | |
241 | print $lineprefix, $blankline; | |
242 | } else { | |
243 | $line =~ s/\\\\\\/\&/g; | |
244 | print $lineprefix, $line; | |
245 | } | |
246 | print "\n"; | |
247 | } | |
248 | } | |
249 | ||
250 | ||
251 | # output in html | |
252 | sub output_html { | |
253 | my %args = %{$_[0]}; | |
254 | my ($parameter, $section); | |
255 | my $count; | |
256 | print "<h2>Function</h2>\n"; | |
257 | ||
258 | print "<i>".$args{'functiontype'}."</i>\n"; | |
259 | print "<b>".$args{'function'}."</b>\n"; | |
260 | print "("; | |
261 | $count = 0; | |
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>"; | |
267 | } else { | |
268 | print "<i>".$type."</i> <b>".$parameter."</b>"; | |
269 | } | |
270 | if ($count != $#{$args{'parameterlist'}}) { | |
271 | $count++; | |
272 | print ",\n"; | |
273 | } | |
274 | } | |
275 | print ")\n"; | |
276 | ||
277 | print "<h3>Arguments</h3>\n"; | |
278 | print "<dl>\n"; | |
279 | foreach $parameter (@{$args{'parameterlist'}}) { | |
280 | print "<dt><b>".$parameter."</b>\n"; | |
281 | print "<dd>"; | |
282 | output_highlight($args{'parameters'}{$parameter}); | |
283 | } | |
284 | print "</dl>\n"; | |
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"; | |
290 | } | |
291 | print "<hr>\n"; | |
292 | } | |
293 | ||
294 | ||
295 | # output in html | |
296 | sub output_intro_html { | |
297 | my %args = %{$_[0]}; | |
298 | my ($parameter, $section); | |
299 | my $count; | |
300 | ||
301 | foreach $section (@{$args{'sectionlist'}}) { | |
302 | print "<h3>$section</h3>\n"; | |
303 | print "<ul>\n"; | |
304 | output_highlight($args{'sections'}{$section}); | |
305 | print "</ul>\n"; | |
306 | } | |
307 | print "<hr>\n"; | |
308 | } | |
309 | ||
310 | ||
311 | ||
312 | # output in sgml DocBook | |
313 | sub output_sgml { | |
314 | my %args = %{$_[0]}; | |
315 | my ($parameter, $section); | |
316 | my $count; | |
317 | my $id; | |
318 | ||
319 | $id = "API-".$args{'function'}; | |
320 | $id =~ s/[^A-Za-z0-9]/-/g; | |
321 | ||
322 | print "<refentry>\n"; | |
323 | print "<refmeta>\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"; | |
332 | ||
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"; | |
339 | ||
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"; | |
346 | ||
347 | $count = 0; | |
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"; | |
355 | } else { | |
356 | print " <paramdef>".$type; | |
357 | print " <parameter>$parameter</parameter></paramdef>\n"; | |
358 | } | |
359 | } | |
360 | } else { | |
361 | print " <void>\n"; | |
362 | } | |
363 | print " </funcsynopsis>\n"; | |
364 | print "</refsynopsisdiv>\n"; | |
365 | # print "</refsect1>\n"; | |
366 | ||
367 | # print parameters | |
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"; | |
375 | $lineprefix=" "; | |
376 | output_highlight($args{'parameters'}{$parameter}); | |
377 | print " </para>\n </listitem>\n </varlistentry>\n"; | |
378 | } | |
379 | print " </variablelist>\n"; | |
380 | } else { | |
381 | print " <para>\n None\n </para>\n"; | |
382 | } | |
383 | print "</refsect1>\n"; | |
384 | ||
385 | # print out each section | |
386 | $lineprefix=" "; | |
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"; | |
392 | } | |
393 | output_highlight($args{'sections'}{$section}); | |
394 | # print "</para>"; | |
395 | if ($section =~ m/EXAMPLE/i) { | |
396 | print "</para></example>\n"; | |
397 | } | |
398 | print " </para>\n</refsect1>\n"; | |
399 | } | |
400 | ||
401 | print "</refentry>\n\n"; | |
402 | } | |
403 | ||
404 | # output in sgml DocBook | |
405 | sub output_intro_sgml { | |
406 | my %args = %{$_[0]}; | |
407 | my ($parameter, $section); | |
408 | my $count; | |
409 | my $id; | |
410 | ||
411 | $id = $args{'module'}; | |
412 | $id =~ s/[^A-Za-z0-9]/-/g; | |
413 | ||
414 | # print out each section | |
415 | $lineprefix=" "; | |
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"; | |
421 | } | |
422 | output_highlight($args{'sections'}{$section}); | |
423 | # print "</para>"; | |
424 | if ($section =~ m/EXAMPLE/i) { | |
425 | print "</para></example>\n"; | |
426 | } | |
427 | print " </para>\n</refsect1>\n"; | |
428 | } | |
429 | ||
430 | print "\n\n"; | |
431 | } | |
432 | ||
433 | # output in sgml DocBook | |
434 | sub output_gnome { | |
435 | my %args = %{$_[0]}; | |
436 | my ($parameter, $section); | |
437 | my $count; | |
438 | my $id; | |
439 | ||
440 | $id = $args{'module'}."-".$args{'function'}; | |
441 | $id =~ s/[^A-Za-z0-9]/-/g; | |
442 | ||
443 | print "<sect2>\n"; | |
444 | print " <title id=\"$id\">".$args{'function'}."</title>\n"; | |
445 | ||
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"; | |
452 | ||
453 | $count = 0; | |
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"; | |
461 | } else { | |
462 | print " <paramdef>".$type; | |
463 | print " <parameter>$parameter</parameter></paramdef>\n"; | |
464 | } | |
465 | } | |
466 | } else { | |
467 | print " <void>\n"; | |
468 | } | |
469 | print " </funcsynopsis>\n"; | |
470 | # print "</simplesect>\n"; | |
471 | # print "</refsect1>\n"; | |
472 | ||
473 | # print parameters | |
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"; | |
480 | # $lineprefix=" "; | |
481 | # output_highlight($args{'parameters'}{$parameter}); | |
482 | # print " </para>\n </listitem>\n </varlistentry>\n"; | |
483 | # } | |
484 | # print " </variablelist>\n"; | |
485 | # } else { | |
486 | # print " <para>\n None\n </para>\n"; | |
487 | # } | |
488 | # print "</simplesect>\n"; | |
489 | ||
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"; | |
496 | print "<tbody>\n"; | |
497 | foreach $parameter (@{$args{'parameterlist'}}) { | |
498 | print " <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n"; | |
499 | print " <entry>\n"; | |
500 | $lineprefix=" "; | |
501 | output_highlight($args{'parameters'}{$parameter}); | |
502 | print " </entry></row>\n"; | |
503 | } | |
504 | print " </tbody></tgroup></informaltable>\n"; | |
505 | } else { | |
506 | print " <para>\n None\n </para>\n"; | |
507 | } | |
508 | # print "</simplesect>\n"; | |
509 | ||
510 | # print out each section | |
511 | $lineprefix=" "; | |
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"; | |
517 | } else { | |
518 | } | |
519 | print "<para>\n"; | |
520 | output_highlight($args{'sections'}{$section}); | |
521 | # print "</para>"; | |
522 | print "</para>\n"; | |
523 | if ($section =~ m/EXAMPLE/i) { | |
524 | print "</programlisting></example>\n"; | |
525 | } else { | |
526 | } | |
527 | print " </simplesect>\n"; | |
528 | } | |
529 | ||
530 | print "</sect2>\n\n"; | |
531 | } | |
532 | ||
533 | ## | |
534 | # output in man | |
535 | sub output_man { | |
536 | my %args = %{$_[0]}; | |
537 | my ($parameter, $section); | |
538 | my $count; | |
539 | ||
540 | print ".TH \"$args{'module'}\" 3 \"$args{'function'}\" \"25 May 1998\" \"API Manual\" libfaim\n"; | |
541 | ||
542 | print ".SH NAME\n"; | |
543 | print $args{'function'}." \\- ".$args{'purpose'}."\n"; | |
544 | ||
545 | print ".SH SYNOPSIS\n"; | |
546 | print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n"; | |
547 | $count = 0; | |
548 | $parenth = "("; | |
549 | $post = ","; | |
550 | foreach $parameter (@{$args{'parameterlist'}}) { | |
551 | if ($count == $#{$args{'parameterlist'}}) { | |
552 | $post = ");"; | |
553 | } | |
554 | $type = $args{'parametertypes'}{$parameter}; | |
555 | if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { | |
556 | # pointer-to-function | |
557 | print ".BI \"".$parenth.$1."\" ".$parameter." \") (".$2.")".$post."\"\n"; | |
558 | } else { | |
559 | $type =~ s/([^\*])$/\1 /; | |
560 | print ".BI \"".$parenth.$type."\" ".$parameter." \"".$post."\"\n"; | |
561 | } | |
562 | $count++; | |
563 | $parenth = ""; | |
564 | } | |
565 | ||
566 | print ".SH Arguments\n"; | |
567 | foreach $parameter (@{$args{'parameterlist'}}) { | |
568 | print ".IP \"".$parameter."\" 12\n"; | |
569 | output_highlight($args{'parameters'}{$parameter}); | |
570 | } | |
571 | foreach $section (@{$args{'sectionlist'}}) { | |
572 | print ".SH \"$section\"\n"; | |
573 | output_highlight($args{'sections'}{$section}); | |
574 | } | |
575 | } | |
576 | ||
577 | sub output_intro_man { | |
578 | my %args = %{$_[0]}; | |
579 | my ($parameter, $section); | |
580 | my $count; | |
581 | ||
582 | print ".TH \"$args{'module'}\" 3 \"$args{'module'}\" \"25 May 1998\" \"API Manual\" libfaim\n"; | |
583 | ||
584 | foreach $section (@{$args{'sectionlist'}}) { | |
585 | print ".SH \"$section\"\n"; | |
586 | output_highlight($args{'sections'}{$section}); | |
587 | } | |
588 | } | |
589 | ||
590 | ## | |
591 | # output in text | |
592 | sub output_text { | |
593 | my %args = %{$_[0]}; | |
594 | my ($parameter, $section); | |
595 | ||
596 | print "Function:\n\n"; | |
597 | $start=$args{'functiontype'}." ".$args{'function'}." ("; | |
598 | print $start; | |
599 | $count = 0; | |
600 | foreach $parameter (@{$args{'parameterlist'}}) { | |
601 | if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { | |
602 | # pointer-to-function | |
603 | print $1.$parameter.") (".$2; | |
604 | } else { | |
605 | print $type." ".$parameter; | |
606 | } | |
607 | if ($count != $#{$args{'parameterlist'}}) { | |
608 | $count++; | |
609 | print ",\n"; | |
610 | print " " x length($start); | |
611 | } else { | |
612 | print ");\n\n"; | |
613 | } | |
614 | } | |
615 | ||
616 | print "Arguments:\n\n"; | |
617 | foreach $parameter (@{$args{'parameterlist'}}) { | |
618 | print $parameter."\n\t".$args{'parameters'}{$parameter}."\n"; | |
619 | } | |
620 | foreach $section (@{$args{'sectionlist'}}) { | |
621 | print "$section:\n\n"; | |
622 | output_highlight($args{'sections'}{$section}); | |
623 | } | |
624 | print "\n\n"; | |
625 | } | |
626 | ||
627 | sub output_intro_text { | |
628 | my %args = %{$_[0]}; | |
629 | my ($parameter, $section); | |
630 | ||
631 | foreach $section (@{$args{'sectionlist'}}) { | |
632 | print " $section:\n"; | |
633 | print " -> "; | |
634 | output_highlight($args{'sections'}{$section}); | |
635 | } | |
636 | } | |
637 | ||
638 | ## | |
639 | # generic output function - calls the right one based | |
640 | # on current output mode. | |
641 | sub output_function { | |
642 | # output_html(@_); | |
643 | eval "output_".$output_mode."(\@_);"; | |
644 | } | |
645 | ||
646 | ## | |
647 | # generic output function - calls the right one based | |
648 | # on current output mode. | |
649 | sub output_intro { | |
650 | # output_html(@_); | |
651 | eval "output_intro_".$output_mode."(\@_);"; | |
652 | } | |
653 | ||
654 | ||
655 | ## | |
656 | # takes a function prototype and spits out all the details | |
657 | # stored in the global arrays/hsahes. | |
658 | sub dump_function { | |
659 | my $prototype = shift @_; | |
660 | ||
661 | $prototype =~ s/^static+ //; | |
662 | $prototype =~ s/^extern+ //; | |
663 | $prototype =~ s/^inline+ //; | |
664 | $prototype =~ s/^__inline__+ //; | |
665 | $prototype =~ s/^faim_export+ //; | |
666 | $prototype =~ s/^faim_internal+ //; | |
667 | ||
668 | if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || | |
669 | $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || | |
670 | $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || | |
671 | $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || | |
672 | $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) { | |
673 | $return_type = $1; | |
674 | $function_name = $2; | |
675 | $args = $3; | |
676 | ||
677 | # allow for up to fours args to function pointers | |
678 | $args =~ s/(\([^\),]+),/\1#/g; | |
679 | $args =~ s/(\([^\),]+),/\1#/g; | |
680 | $args =~ s/(\([^\),]+),/\1#/g; | |
681 | # print STDERR "ARGS = '$args'\n"; | |
682 | ||
683 | foreach $arg (split ',', $args) { | |
684 | # strip leading/trailing spaces | |
685 | $arg =~ s/^\s*//; | |
686 | $arg =~ s/\s*$//; | |
687 | ||
688 | if ($arg =~ m/\(/) { | |
689 | # pointer-to-function | |
690 | $arg =~ tr/#/,/; | |
691 | $arg =~ m/[^\(]+\(\*([^\)]+)\)/; | |
692 | $param = $1; | |
693 | $type = $arg; | |
694 | $type =~ s/([^\(]+\(\*)$param/\1/; | |
695 | } else { | |
696 | # evil magic to get fixed array parameters to work | |
697 | $arg =~ s/(.+\s+)(.+)\[.*/\1* \2/; | |
698 | # print STDERR "SCAN ARG: '$arg'\n"; | |
699 | @args = split('\s', $arg); | |
700 | ||
701 | # print STDERR " -> @args\n"; | |
702 | $param = pop @args; | |
703 | # print STDERR " -> @args\n"; | |
704 | if ($param =~ m/^(\*+)(.*)/) { | |
705 | $param = $2; | |
706 | push @args, $1; | |
707 | } | |
708 | $type = join " ", @args; | |
709 | } | |
710 | ||
711 | if ($type eq "" && $param eq "...") | |
712 | { | |
713 | $type="..."; | |
714 | $param="..."; | |
715 | $parameters{"..."} = "variable arguments"; | |
716 | } | |
717 | if ($type eq "") | |
718 | { | |
719 | $type=""; | |
720 | $param="void"; | |
721 | $parameters{void} = "no arguments"; | |
722 | } | |
723 | if ($parameters{$param} eq "") { | |
724 | $parameters{$param} = "-- undescribed --"; | |
725 | print STDERR "Warning($file:$lineno): Function parameter '$param' not described in '$function_name'\n"; | |
726 | } | |
727 | ||
728 | push @parameterlist, $param; | |
729 | $parametertypes{$param} = $type; | |
730 | # print STDERR "param = '$param', type = '$type'\n"; | |
731 | } | |
732 | } else { | |
733 | print STDERR "Error($lineno): cannot understand prototype: '$prototype'\n"; | |
734 | return; | |
735 | } | |
736 | ||
737 | if ($function_only==0 || | |
738 | ( $function_only == 1 && defined($function_table{$function_name})) || | |
739 | ( $function_only == 2 && !defined($function_table{$function_name}))) | |
740 | { | |
741 | output_function({'function' => $function_name, | |
742 | 'module' => $modulename, | |
743 | 'functiontype' => $return_type, | |
744 | 'parameterlist' => \@parameterlist, | |
745 | 'parameters' => \%parameters, | |
746 | 'parametertypes' => \%parametertypes, | |
747 | 'sectionlist' => \@sectionlist, | |
748 | 'sections' => \%sections, | |
749 | 'purpose' => $function_purpose | |
750 | }); | |
751 | } | |
752 | } | |
753 | ||
754 | ###################################################################### | |
755 | # main | |
756 | # states | |
757 | # 0 - normal code | |
758 | # 1 - looking for function name | |
759 | # 2 - scanning field start. | |
760 | # 3 - scanning prototype. | |
761 | $state = 0; | |
762 | $section = ""; | |
763 | ||
764 | $doc_special = "\@\%\$\&"; | |
765 | ||
766 | $doc_start = "^/\\*\\*\$"; | |
767 | $doc_end = "\\*/"; | |
768 | $doc_com = "\\s*\\*\\s*"; | |
769 | $doc_func = $doc_com."(\\w+):?"; | |
770 | $doc_sect = $doc_com."([".$doc_special."]?[\\w ]+):(.*)"; | |
771 | $doc_content = $doc_com."(.*)"; | |
772 | $doc_block = $doc_com."DOC:\\s*(.*)?"; | |
773 | ||
774 | %constants = (); | |
775 | %parameters = (); | |
776 | @parameterlist = (); | |
777 | %sections = (); | |
778 | @sectionlist = (); | |
779 | ||
780 | $contents = ""; | |
781 | $section_default = "Description"; # default section | |
782 | $section_intro = "Introduction"; | |
783 | $section = $section_default; | |
784 | ||
785 | $lineno = 0; | |
786 | foreach $file (@ARGV) { | |
787 | chomp($file); | |
788 | if (!open(IN,"<$file")) { | |
789 | print STDERR "Error: Cannot open file $file\n"; | |
790 | next; | |
791 | } | |
792 | while (<IN>) { | |
793 | $lineno++; | |
794 | ||
795 | if ($state == 0) { | |
796 | if (/$doc_start/o) { | |
797 | $state = 1; # next line is always the function name | |
798 | } | |
799 | } elsif ($state == 1) { # this line is the function name (always) | |
800 | if (/$doc_block/o) { | |
801 | $state = 4; | |
802 | $contents = ""; | |
803 | if ( $1 eq "" ) { | |
804 | $section = $section_intro; | |
805 | } else { | |
806 | $section = $1; | |
807 | } | |
808 | } | |
809 | elsif (/$doc_func/o) { | |
810 | $function = $1; | |
811 | $state = 2; | |
812 | if (/-(.*)/) { | |
813 | $function_purpose = $1; | |
814 | } else { | |
815 | $function_purpose = ""; | |
816 | } | |
817 | if ($verbose) { | |
818 | print STDERR "Info($lineno): Scanning doc for $function\n"; | |
819 | } | |
820 | } else { | |
821 | print STDERR "WARN($lineno): Cannot understand $_ on line $lineno", | |
822 | " - I thought it was a doc line\n"; | |
823 | $state = 0; | |
824 | } | |
825 | } elsif ($state == 2) { # look for head: lines, and include content | |
826 | if (/$doc_sect/o) { | |
827 | $newsection = $1; | |
828 | $newcontents = $2; | |
829 | ||
830 | if ($contents ne "") { | |
831 | $contents =~ s/\&/\\\\\\amp;/g; | |
832 | $contents =~ s/\</\\\\\\lt;/g; | |
833 | $contents =~ s/\>/\\\\\\gt;/g; | |
834 | dump_section($section, $contents); | |
835 | $section = $section_default; | |
836 | } | |
837 | ||
838 | $contents = $newcontents; | |
839 | if ($contents ne "") { | |
840 | $contents .= "\n"; | |
841 | } | |
842 | $section = $newsection; | |
843 | } elsif (/$doc_end/) { | |
844 | ||
845 | if ($contents ne "") { | |
846 | $contents =~ s/\&/\\\\\\amp;/g; | |
847 | $contents =~ s/\</\\\\\\lt;/g; | |
848 | $contents =~ s/\>/\\\\\\gt;/g; | |
849 | dump_section($section, $contents); | |
850 | $section = $section_default; | |
851 | $contents = ""; | |
852 | } | |
853 | ||
854 | # print STDERR "end of doc comment, looking for prototype\n"; | |
855 | $prototype = ""; | |
856 | $state = 3; | |
857 | } elsif (/$doc_content/) { | |
858 | # miguel-style comment kludge, look for blank lines after | |
859 | # @parameter line to signify start of description | |
860 | if ($1 eq "" && $section =~ m/^@/) { | |
861 | $contents =~ s/\&/\\\\\\amp;/g; | |
862 | $contents =~ s/\</\\\\\\lt;/g; | |
863 | $contents =~ s/\>/\\\\\\gt;/g; | |
864 | dump_section($section, $contents); | |
865 | $section = $section_default; | |
866 | $contents = ""; | |
867 | } else { | |
868 | $contents .= $1."\n"; | |
869 | } | |
870 | } else { | |
871 | # i dont know - bad line? ignore. | |
872 | print STDERR "WARNING($lineno): bad line: $_"; | |
873 | } | |
874 | } elsif ($state == 3) { # scanning for function { (end of prototype) | |
875 | if (m#\s*/\*\s+MACDOC\s*#io) { | |
876 | # do nothing | |
877 | } | |
878 | elsif (/([^\{]*)/) { | |
879 | $prototype .= $1; | |
880 | } | |
881 | if (/\{/) { | |
882 | $prototype =~ s@/\*.*?\*/@@gos; # strip comments. | |
883 | $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's. | |
884 | $prototype =~ s@^ +@@gos; # strip leading spaces | |
885 | dump_function($prototype); | |
886 | ||
887 | $function = ""; | |
888 | %constants = (); | |
889 | %parameters = (); | |
890 | %parametertypes = (); | |
891 | @parameterlist = (); | |
892 | %sections = (); | |
893 | @sectionlist = (); | |
894 | $prototype = ""; | |
895 | ||
896 | $state = 0; | |
897 | } | |
898 | } elsif ($state == 4) { | |
899 | # Documentation block | |
900 | if (/$doc_block/) { | |
901 | dump_section($section, $contents); | |
902 | output_intro({'sectionlist' => \@sectionlist, | |
903 | 'sections' => \%sections }); | |
904 | $contents = ""; | |
905 | $function = ""; | |
906 | %constants = (); | |
907 | %parameters = (); | |
908 | %parametertypes = (); | |
909 | @parameterlist = (); | |
910 | %sections = (); | |
911 | @sectionlist = (); | |
912 | $prototype = ""; | |
913 | if ( $1 eq "" ) { | |
914 | $section = $section_intro; | |
915 | } else { | |
916 | $section = $1; | |
917 | } | |
918 | } | |
919 | elsif (/$doc_end/) | |
920 | { | |
921 | dump_section($section, $contents); | |
922 | output_intro({'sectionlist' => \@sectionlist, | |
923 | 'sections' => \%sections }); | |
924 | $contents = ""; | |
925 | $function = ""; | |
926 | %constants = (); | |
927 | %parameters = (); | |
928 | %parametertypes = (); | |
929 | @parameterlist = (); | |
930 | %sections = (); | |
931 | @sectionlist = (); | |
932 | $prototype = ""; | |
933 | $state = 0; | |
934 | } | |
935 | elsif (/$doc_content/) | |
936 | { | |
937 | if ( $1 eq "" ) | |
938 | { | |
939 | $contents .= $blankline; | |
940 | } | |
941 | else | |
942 | { | |
943 | $contents .= $1 . "\n"; | |
944 | } | |
945 | } | |
946 | } | |
947 | } | |
948 | } | |
949 |