Statistics
| Branch: | Revision:

iof-bird / bird-2.0.1 / doc / kernel-doc @ 6b3f1a54

History | View | Annotate | Download (25.4 KB)

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