xref: /linux/scripts/kernel-doc (revision 51f5a0c8f63990fcb6e09ed52be348df58c9e416)
1#!/usr/bin/perl -w
2
3use strict;
4
5## Copyright (c) 1998 Michael Zucchi, All Rights Reserved        ##
6## Copyright (C) 2000, 1  Tim Waugh <twaugh@redhat.com>          ##
7## Copyright (C) 2001  Simon Huggins                             ##
8## 								 ##
9## #define enhancements by Armin Kuster <akuster@mvista.com>	 ##
10## Copyright (c) 2000 MontaVista Software, Inc.			 ##
11## 								 ##
12## This software falls under the GNU General Public License.     ##
13## Please read the COPYING file for more information             ##
14
15# w.o. 03-11-2000: added the '-filelist' option.
16
17# 18/01/2001 - 	Cleanups
18# 		Functions prototyped as foo(void) same as foo()
19# 		Stop eval'ing where we don't need to.
20# -- huggie@earth.li
21
22# 27/06/2001 -  Allowed whitespace after initial "/**" and
23#               allowed comments before function declarations.
24# -- Christian Kreibich <ck@whoop.org>
25
26# Still to do:
27# 	- add perldoc documentation
28# 	- Look more closely at some of the scarier bits :)
29
30# 26/05/2001 - 	Support for separate source and object trees.
31#		Return error code.
32# 		Keith Owens <kaos@ocs.com.au>
33
34# 23/09/2001 - Added support for typedefs, structs, enums and unions
35#              Support for Context section; can be terminated using empty line
36#              Small fixes (like spaces vs. \s in regex)
37# -- Tim Jansen <tim@tjansen.de>
38
39
40#
41# This will read a 'c' file and scan for embedded comments in the
42# style of gnome comments (+minor extensions - see below).
43#
44
45# Note: This only supports 'c'.
46
47# usage:
48# kernel-doc [ -docbook | -html | -text | -man ]
49#           [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
50# or
51#           [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile
52#
53#  Set output format using one of -docbook -html -text or -man.  Default is man.
54#
55#  -function funcname
56#	If set, then only generate documentation for the given function(s).  All
57#	other functions are ignored.
58#
59#  -nofunction funcname
60#	If set, then only generate documentation for the other function(s).
61#	Cannot be used together with -function
62#	(yes, that's a bug -- perl hackers can fix it 8))
63#
64#  c files - list of 'c' files to process
65#
66#  All output goes to stdout, with errors to stderr.
67
68#
69# format of comments.
70# In the following table, (...)? signifies optional structure.
71#                         (...)* signifies 0 or more structure elements
72# /**
73#  * function_name(:)? (- short description)?
74# (* @parameterx: (description of parameter x)?)*
75# (* a blank line)?
76#  * (Description:)? (Description of function)?
77#  * (section header: (section description)? )*
78#  (*)?*/
79#
80# So .. the trivial example would be:
81#
82# /**
83#  * my_function
84#  **/
85#
86# If the Description: header tag is omitted, then there must be a blank line
87# after the last parameter specification.
88# e.g.
89# /**
90#  * my_function - does my stuff
91#  * @my_arg: its mine damnit
92#  *
93#  * Does my stuff explained.
94#  */
95#
96#  or, could also use:
97# /**
98#  * my_function - does my stuff
99#  * @my_arg: its mine damnit
100#  * Description: Does my stuff explained.
101#  */
102# etc.
103#
104# Beside functions you can also write documentation for structs, unions,
105# enums and typedefs. Instead of the function name you must write the name
106# of the declaration;  the struct/union/enum/typedef must always precede
107# the name. Nesting of declarations is not supported.
108# Use the argument mechanism to document members or constants.
109# e.g.
110# /**
111#  * struct my_struct - short description
112#  * @a: first member
113#  * @b: second member
114#  *
115#  * Longer description
116#  */
117# struct my_struct {
118#     int a;
119#     int b;
120# /* private: */
121#     int c;
122# };
123#
124# All descriptions can be multiline, except the short function description.
125#
126# You can also add additional sections. When documenting kernel functions you
127# should document the "Context:" of the function, e.g. whether the functions
128# can be called form interrupts. Unlike other sections you can end it with an
129# empty line.
130# Example-sections should contain the string EXAMPLE so that they are marked
131# appropriately in DocBook.
132#
133# Example:
134# /**
135#  * user_function - function that can only be called in user context
136#  * @a: some argument
137#  * Context: !in_interrupt()
138#  *
139#  * Some description
140#  * Example:
141#  *    user_function(22);
142#  */
143# ...
144#
145#
146# All descriptive text is further processed, scanning for the following special
147# patterns, which are highlighted appropriately.
148#
149# 'funcname()' - function
150# '$ENVVAR' - environmental variable
151# '&struct_name' - name of a structure (up to two words including 'struct')
152# '@parameter' - name of a parameter
153# '%CONST' - name of a constant.
154
155my $errors = 0;
156my $warnings = 0;
157my $anon_struct_union = 0;
158
159# match expressions used to find embedded type information
160my $type_constant = '\%([-_\w]+)';
161my $type_func = '(\w+)\(\)';
162my $type_param = '\@(\w+)';
163my $type_struct = '\&((struct\s*)*[_\w]+)';
164my $type_struct_xml = '\\\amp;((struct\s*)*[_\w]+)';
165my $type_env = '(\$\w+)';
166
167# Output conversion substitutions.
168#  One for each output format
169
170# these work fairly well
171my %highlights_html = ( $type_constant, "<i>\$1</i>",
172			$type_func, "<b>\$1</b>",
173			$type_struct_xml, "<i>\$1</i>",
174			$type_env, "<b><i>\$1</i></b>",
175			$type_param, "<tt><b>\$1</b></tt>" );
176my $blankline_html = "<p>";
177
178# XML, docbook format
179my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
180			$type_constant, "<constant>\$1</constant>",
181			$type_func, "<function>\$1</function>",
182			$type_struct, "<structname>\$1</structname>",
183			$type_env, "<envar>\$1</envar>",
184			$type_param, "<parameter>\$1</parameter>" );
185my $blankline_xml = "</para><para>\n";
186
187# gnome, docbook format
188my %highlights_gnome = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",
189			 $type_func, "<function>\$1</function>",
190			 $type_struct, "<structname>\$1</structname>",
191			 $type_env, "<envar>\$1</envar>",
192			 $type_param, "<parameter>\$1</parameter>" );
193my $blankline_gnome = "</para><para>\n";
194
195# these are pretty rough
196my %highlights_man = ( $type_constant, "\$1",
197		       $type_func, "\\\\fB\$1\\\\fP",
198		       $type_struct, "\\\\fI\$1\\\\fP",
199		       $type_param, "\\\\fI\$1\\\\fP" );
200my $blankline_man = "";
201
202# text-mode
203my %highlights_text = ( $type_constant, "\$1",
204			$type_func, "\$1",
205			$type_struct, "\$1",
206			$type_param, "\$1" );
207my $blankline_text = "";
208
209
210sub usage {
211    print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ]\n";
212    print "         [ -function funcname [ -function funcname ...] ]\n";
213    print "         [ -nofunction funcname [ -nofunction funcname ...] ]\n";
214    print "         c source file(s) > outputfile\n";
215    exit 1;
216}
217
218# read arguments
219if ($#ARGV==-1) {
220    usage();
221}
222
223my $verbose = 0;
224my $output_mode = "man";
225my %highlights = %highlights_man;
226my $blankline = $blankline_man;
227my $modulename = "Kernel API";
228my $function_only = 0;
229my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
230		'July', 'August', 'September', 'October',
231		'November', 'December')[(localtime)[4]] .
232  " " . ((localtime)[5]+1900);
233
234# Essentially these are globals
235# They probably want to be tidied up made more localised or summat.
236# CAVEAT EMPTOR!  Some of the others I localised may not want to be which
237# could cause "use of undefined value" or other bugs.
238my ($function, %function_table,%parametertypes,$declaration_purpose);
239my ($type,$declaration_name,$return_type);
240my ($newsection,$newcontents,$prototype,$filelist, $brcount, %source_map);
241
242# Generated docbook code is inserted in a template at a point where
243# docbook v3.1 requires a non-zero sequence of RefEntry's; see:
244# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
245# We keep track of number of generated entries and generate a dummy
246# if needs be to ensure the expanded template can be postprocessed
247# into html.
248my $section_counter = 0;
249
250my $lineprefix="";
251
252# states
253# 0 - normal code
254# 1 - looking for function name
255# 2 - scanning field start.
256# 3 - scanning prototype.
257# 4 - documentation block
258my $state;
259my $in_doc_sect;
260
261#declaration types: can be
262# 'function', 'struct', 'union', 'enum', 'typedef'
263my $decl_type;
264
265my $doc_special = "\@\%\$\&";
266
267my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
268my $doc_end = '\*/';
269my $doc_com = '\s*\*\s*';
270my $doc_decl = $doc_com.'(\w+)';
271my $doc_sect = $doc_com.'(['.$doc_special.']?[\w\s]+):(.*)';
272my $doc_content = $doc_com.'(.*)';
273my $doc_block = $doc_com.'DOC:\s*(.*)?';
274
275my %constants;
276my %parameterdescs;
277my @parameterlist;
278my %sections;
279my @sectionlist;
280
281my $contents = "";
282my $section_default = "Description";	# default section
283my $section_intro = "Introduction";
284my $section = $section_default;
285my $section_context = "Context";
286
287my $undescribed = "-- undescribed --";
288
289reset_state();
290
291while ($ARGV[0] =~ m/^-(.*)/) {
292    my $cmd = shift @ARGV;
293    if ($cmd eq "-html") {
294	$output_mode = "html";
295	%highlights = %highlights_html;
296	$blankline = $blankline_html;
297    } elsif ($cmd eq "-man") {
298	$output_mode = "man";
299	%highlights = %highlights_man;
300	$blankline = $blankline_man;
301    } elsif ($cmd eq "-text") {
302	$output_mode = "text";
303	%highlights = %highlights_text;
304	$blankline = $blankline_text;
305    } elsif ($cmd eq "-docbook") {
306	$output_mode = "xml";
307	%highlights = %highlights_xml;
308	$blankline = $blankline_xml;
309    } elsif ($cmd eq "-gnome") {
310	$output_mode = "gnome";
311	%highlights = %highlights_gnome;
312	$blankline = $blankline_gnome;
313    } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
314	$modulename = shift @ARGV;
315    } elsif ($cmd eq "-function") { # to only output specific functions
316	$function_only = 1;
317	$function = shift @ARGV;
318	$function_table{$function} = 1;
319    } elsif ($cmd eq "-nofunction") { # to only output specific functions
320	$function_only = 2;
321	$function = shift @ARGV;
322	$function_table{$function} = 1;
323    } elsif ($cmd eq "-v") {
324	$verbose = 1;
325    } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
326	usage();
327    } elsif ($cmd eq '-filelist') {
328	    $filelist = shift @ARGV;
329    }
330}
331
332# get kernel version from env
333sub get_kernel_version() {
334    my $version;
335
336    if (defined($ENV{'KERNELVERSION'})) {
337	$version = $ENV{'KERNELVERSION'};
338    }
339    return $version;
340}
341my $kernelversion = get_kernel_version();
342
343# generate a sequence of code that will splice in highlighting information
344# using the s// operator.
345my $dohighlight = "";
346foreach my $pattern (keys %highlights) {
347#   print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n";
348    $dohighlight .=  "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
349}
350
351##
352# dumps section contents to arrays/hashes intended for that purpose.
353#
354sub dump_section {
355    my $name = shift;
356    my $contents = join "\n", @_;
357
358    if ($name =~ m/$type_constant/) {
359	$name = $1;
360#	print STDERR "constant section '$1' = '$contents'\n";
361	$constants{$name} = $contents;
362    } elsif ($name =~ m/$type_param/) {
363#	print STDERR "parameter def '$1' = '$contents'\n";
364	$name = $1;
365	$parameterdescs{$name} = $contents;
366    } else {
367#	print STDERR "other section '$name' = '$contents'\n";
368	$sections{$name} = $contents;
369	push @sectionlist, $name;
370    }
371}
372
373##
374# output function
375#
376# parameterdescs, a hash.
377#  function => "function name"
378#  parameterlist => @list of parameters
379#  parameterdescs => %parameter descriptions
380#  sectionlist => @list of sections
381#  sections => %section descriptions
382#
383
384sub output_highlight {
385    my $contents = join "\n",@_;
386    my $line;
387
388#   DEBUG
389#   if (!defined $contents) {
390#	use Carp;
391#	confess "output_highlight got called with no args?\n";
392#   }
393
394#   print STDERR "contents b4:$contents\n";
395    eval $dohighlight;
396    die $@ if $@;
397    if ($output_mode eq "html") {
398	$contents =~ s/\\\\//;
399    }
400#   print STDERR "contents af:$contents\n";
401
402    foreach $line (split "\n", $contents) {
403	if ($line eq ""){
404	    print $lineprefix, $blankline;
405	} else {
406	    $line =~ s/\\\\\\/\&/g;
407	    print $lineprefix, $line;
408	}
409	print "\n";
410    }
411}
412
413#output sections in html
414sub output_section_html(%) {
415    my %args = %{$_[0]};
416    my $section;
417
418    foreach $section (@{$args{'sectionlist'}}) {
419	print "<h3>$section</h3>\n";
420	print "<blockquote>\n";
421	output_highlight($args{'sections'}{$section});
422	print "</blockquote>\n";
423    }
424}
425
426# output enum in html
427sub output_enum_html(%) {
428    my %args = %{$_[0]};
429    my ($parameter);
430    my $count;
431    print "<h2>enum ".$args{'enum'}."</h2>\n";
432
433    print "<b>enum ".$args{'enum'}."</b> {<br>\n";
434    $count = 0;
435    foreach $parameter (@{$args{'parameterlist'}}) {
436	print " <b>".$parameter."</b>";
437	if ($count != $#{$args{'parameterlist'}}) {
438	    $count++;
439	    print ",\n";
440	}
441	print "<br>";
442    }
443    print "};<br>\n";
444
445    print "<h3>Constants</h3>\n";
446    print "<dl>\n";
447    foreach $parameter (@{$args{'parameterlist'}}) {
448	print "<dt><b>".$parameter."</b>\n";
449	print "<dd>";
450	output_highlight($args{'parameterdescs'}{$parameter});
451    }
452    print "</dl>\n";
453    output_section_html(@_);
454    print "<hr>\n";
455}
456
457# output typedef in html
458sub output_typedef_html(%) {
459    my %args = %{$_[0]};
460    my ($parameter);
461    my $count;
462    print "<h2>typedef ".$args{'typedef'}."</h2>\n";
463
464    print "<b>typedef ".$args{'typedef'}."</b>\n";
465    output_section_html(@_);
466    print "<hr>\n";
467}
468
469# output struct in html
470sub output_struct_html(%) {
471    my %args = %{$_[0]};
472    my ($parameter);
473
474    print "<h2>".$args{'type'}." ".$args{'struct'}. " - " .$args{'purpose'}."</h2>\n";
475    print "<b>".$args{'type'}." ".$args{'struct'}."</b> {<br>\n";
476    foreach $parameter (@{$args{'parameterlist'}}) {
477	if ($parameter =~ /^#/) {
478		print "$parameter<br>\n";
479		next;
480	}
481	my $parameter_name = $parameter;
482	$parameter_name =~ s/\[.*//;
483
484	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
485	$type = $args{'parametertypes'}{$parameter};
486	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
487	    # pointer-to-function
488	    print "&nbsp; &nbsp; <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
489	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
490	    # bitfield
491	    print "&nbsp; &nbsp; <i>$1</i> <b>$parameter</b>$2;<br>\n";
492	} else {
493	    print "&nbsp; &nbsp; <i>$type</i> <b>$parameter</b>;<br>\n";
494	}
495    }
496    print "};<br>\n";
497
498    print "<h3>Members</h3>\n";
499    print "<dl>\n";
500    foreach $parameter (@{$args{'parameterlist'}}) {
501	($parameter =~ /^#/) && next;
502
503	my $parameter_name = $parameter;
504	$parameter_name =~ s/\[.*//;
505
506	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
507	print "<dt><b>".$parameter."</b>\n";
508	print "<dd>";
509	output_highlight($args{'parameterdescs'}{$parameter_name});
510    }
511    print "</dl>\n";
512    output_section_html(@_);
513    print "<hr>\n";
514}
515
516# output function in html
517sub output_function_html(%) {
518    my %args = %{$_[0]};
519    my ($parameter, $section);
520    my $count;
521
522    print "<h2>" .$args{'function'}." - ".$args{'purpose'}."</h2>\n";
523    print "<i>".$args{'functiontype'}."</i>\n";
524    print "<b>".$args{'function'}."</b>\n";
525    print "(";
526    $count = 0;
527    foreach $parameter (@{$args{'parameterlist'}}) {
528	$type = $args{'parametertypes'}{$parameter};
529	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
530	    # pointer-to-function
531	    print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
532	} else {
533	    print "<i>".$type."</i> <b>".$parameter."</b>";
534	}
535	if ($count != $#{$args{'parameterlist'}}) {
536	    $count++;
537	    print ",\n";
538	}
539    }
540    print ")\n";
541
542    print "<h3>Arguments</h3>\n";
543    print "<dl>\n";
544    foreach $parameter (@{$args{'parameterlist'}}) {
545	my $parameter_name = $parameter;
546	$parameter_name =~ s/\[.*//;
547
548	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
549	print "<dt><b>".$parameter."</b>\n";
550	print "<dd>";
551	output_highlight($args{'parameterdescs'}{$parameter_name});
552    }
553    print "</dl>\n";
554    output_section_html(@_);
555    print "<hr>\n";
556}
557
558# output intro in html
559sub output_intro_html(%) {
560    my %args = %{$_[0]};
561    my ($parameter, $section);
562    my $count;
563
564    foreach $section (@{$args{'sectionlist'}}) {
565	print "<h3>$section</h3>\n";
566	print "<ul>\n";
567	output_highlight($args{'sections'}{$section});
568	print "</ul>\n";
569    }
570    print "<hr>\n";
571}
572
573sub output_section_xml(%) {
574    my %args = %{$_[0]};
575    my $section;
576    # print out each section
577    $lineprefix="   ";
578    foreach $section (@{$args{'sectionlist'}}) {
579	print "<refsect1>\n";
580	print "<title>$section</title>\n";
581	if ($section =~ m/EXAMPLE/i) {
582	    print "<informalexample><programlisting>\n";
583	} else {
584	    print "<para>\n";
585	}
586	output_highlight($args{'sections'}{$section});
587	if ($section =~ m/EXAMPLE/i) {
588	    print "</programlisting></informalexample>\n";
589	} else {
590	    print "</para>\n";
591	}
592	print "</refsect1>\n";
593    }
594}
595
596# output function in XML DocBook
597sub output_function_xml(%) {
598    my %args = %{$_[0]};
599    my ($parameter, $section);
600    my $count;
601    my $id;
602
603    $id = "API-".$args{'function'};
604    $id =~ s/[^A-Za-z0-9]/-/g;
605
606    print "<refentry id=\"$id\">\n";
607    print "<refentryinfo>\n";
608    print " <title>LINUX</title>\n";
609    print " <productname>Kernel Hackers Manual</productname>\n";
610    print " <date>$man_date</date>\n";
611    print "</refentryinfo>\n";
612    print "<refmeta>\n";
613    print " <refentrytitle><phrase>".$args{'function'}."</phrase></refentrytitle>\n";
614    print " <manvolnum>9</manvolnum>\n";
615    print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
616    print "</refmeta>\n";
617    print "<refnamediv>\n";
618    print " <refname>".$args{'function'}."</refname>\n";
619    print " <refpurpose>\n";
620    print "  ";
621    output_highlight ($args{'purpose'});
622    print " </refpurpose>\n";
623    print "</refnamediv>\n";
624
625    print "<refsynopsisdiv>\n";
626    print " <title>Synopsis</title>\n";
627    print "  <funcsynopsis><funcprototype>\n";
628    print "   <funcdef>".$args{'functiontype'}." ";
629    print "<function>".$args{'function'}." </function></funcdef>\n";
630
631    $count = 0;
632    if ($#{$args{'parameterlist'}} >= 0) {
633	foreach $parameter (@{$args{'parameterlist'}}) {
634	    $type = $args{'parametertypes'}{$parameter};
635	    if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
636		# pointer-to-function
637		print "   <paramdef>$1<parameter>$parameter</parameter>)\n";
638		print "     <funcparams>$2</funcparams></paramdef>\n";
639	    } else {
640		print "   <paramdef>".$type;
641		print " <parameter>$parameter</parameter></paramdef>\n";
642	    }
643	}
644    } else {
645	print "  <void/>\n";
646    }
647    print "  </funcprototype></funcsynopsis>\n";
648    print "</refsynopsisdiv>\n";
649
650    # print parameters
651    print "<refsect1>\n <title>Arguments</title>\n";
652    if ($#{$args{'parameterlist'}} >= 0) {
653	print " <variablelist>\n";
654	foreach $parameter (@{$args{'parameterlist'}}) {
655	    my $parameter_name = $parameter;
656	    $parameter_name =~ s/\[.*//;
657
658	    print "  <varlistentry>\n   <term><parameter>$parameter</parameter></term>\n";
659	    print "   <listitem>\n    <para>\n";
660	    $lineprefix="     ";
661	    output_highlight($args{'parameterdescs'}{$parameter_name});
662	    print "    </para>\n   </listitem>\n  </varlistentry>\n";
663	}
664	print " </variablelist>\n";
665    } else {
666	print " <para>\n  None\n </para>\n";
667    }
668    print "</refsect1>\n";
669
670    output_section_xml(@_);
671    print "</refentry>\n\n";
672}
673
674# output struct in XML DocBook
675sub output_struct_xml(%) {
676    my %args = %{$_[0]};
677    my ($parameter, $section);
678    my $id;
679
680    $id = "API-struct-".$args{'struct'};
681    $id =~ s/[^A-Za-z0-9]/-/g;
682
683    print "<refentry id=\"$id\">\n";
684    print "<refentryinfo>\n";
685    print " <title>LINUX</title>\n";
686    print " <productname>Kernel Hackers Manual</productname>\n";
687    print " <date>$man_date</date>\n";
688    print "</refentryinfo>\n";
689    print "<refmeta>\n";
690    print " <refentrytitle><phrase>".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>\n";
691    print " <manvolnum>9</manvolnum>\n";
692    print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
693    print "</refmeta>\n";
694    print "<refnamediv>\n";
695    print " <refname>".$args{'type'}." ".$args{'struct'}."</refname>\n";
696    print " <refpurpose>\n";
697    print "  ";
698    output_highlight ($args{'purpose'});
699    print " </refpurpose>\n";
700    print "</refnamediv>\n";
701
702    print "<refsynopsisdiv>\n";
703    print " <title>Synopsis</title>\n";
704    print "  <programlisting>\n";
705    print $args{'type'}." ".$args{'struct'}." {\n";
706    foreach $parameter (@{$args{'parameterlist'}}) {
707	if ($parameter =~ /^#/) {
708	    print "$parameter\n";
709	    next;
710	}
711
712	my $parameter_name = $parameter;
713	$parameter_name =~ s/\[.*//;
714
715	defined($args{'parameterdescs'}{$parameter_name}) || next;
716	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
717	$type = $args{'parametertypes'}{$parameter};
718	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
719	    # pointer-to-function
720	    print "  $1 $parameter) ($2);\n";
721	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
722	    # bitfield
723	    print "  $1 $parameter$2;\n";
724	} else {
725	    print "  ".$type." ".$parameter.";\n";
726	}
727    }
728    print "};";
729    print "  </programlisting>\n";
730    print "</refsynopsisdiv>\n";
731
732    print " <refsect1>\n";
733    print "  <title>Members</title>\n";
734
735    print "  <variablelist>\n";
736    foreach $parameter (@{$args{'parameterlist'}}) {
737      ($parameter =~ /^#/) && next;
738
739      my $parameter_name = $parameter;
740      $parameter_name =~ s/\[.*//;
741
742      defined($args{'parameterdescs'}{$parameter_name}) || next;
743      ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
744      print "    <varlistentry>";
745      print "      <term>$parameter</term>\n";
746      print "      <listitem><para>\n";
747      output_highlight($args{'parameterdescs'}{$parameter_name});
748      print "      </para></listitem>\n";
749      print "    </varlistentry>\n";
750    }
751    print "  </variablelist>\n";
752    print " </refsect1>\n";
753
754    output_section_xml(@_);
755
756    print "</refentry>\n\n";
757}
758
759# output enum in XML DocBook
760sub output_enum_xml(%) {
761    my %args = %{$_[0]};
762    my ($parameter, $section);
763    my $count;
764    my $id;
765
766    $id = "API-enum-".$args{'enum'};
767    $id =~ s/[^A-Za-z0-9]/-/g;
768
769    print "<refentry id=\"$id\">\n";
770    print "<refentryinfo>\n";
771    print " <title>LINUX</title>\n";
772    print " <productname>Kernel Hackers Manual</productname>\n";
773    print " <date>$man_date</date>\n";
774    print "</refentryinfo>\n";
775    print "<refmeta>\n";
776    print " <refentrytitle><phrase>enum ".$args{'enum'}."</phrase></refentrytitle>\n";
777    print " <manvolnum>9</manvolnum>\n";
778    print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
779    print "</refmeta>\n";
780    print "<refnamediv>\n";
781    print " <refname>enum ".$args{'enum'}."</refname>\n";
782    print " <refpurpose>\n";
783    print "  ";
784    output_highlight ($args{'purpose'});
785    print " </refpurpose>\n";
786    print "</refnamediv>\n";
787
788    print "<refsynopsisdiv>\n";
789    print " <title>Synopsis</title>\n";
790    print "  <programlisting>\n";
791    print "enum ".$args{'enum'}." {\n";
792    $count = 0;
793    foreach $parameter (@{$args{'parameterlist'}}) {
794	print "  $parameter";
795	if ($count != $#{$args{'parameterlist'}}) {
796	    $count++;
797	    print ",";
798	}
799	print "\n";
800    }
801    print "};";
802    print "  </programlisting>\n";
803    print "</refsynopsisdiv>\n";
804
805    print "<refsect1>\n";
806    print " <title>Constants</title>\n";
807    print "  <variablelist>\n";
808    foreach $parameter (@{$args{'parameterlist'}}) {
809      my $parameter_name = $parameter;
810      $parameter_name =~ s/\[.*//;
811
812      print "    <varlistentry>";
813      print "      <term>$parameter</term>\n";
814      print "      <listitem><para>\n";
815      output_highlight($args{'parameterdescs'}{$parameter_name});
816      print "      </para></listitem>\n";
817      print "    </varlistentry>\n";
818    }
819    print "  </variablelist>\n";
820    print "</refsect1>\n";
821
822    output_section_xml(@_);
823
824    print "</refentry>\n\n";
825}
826
827# output typedef in XML DocBook
828sub output_typedef_xml(%) {
829    my %args = %{$_[0]};
830    my ($parameter, $section);
831    my $id;
832
833    $id = "API-typedef-".$args{'typedef'};
834    $id =~ s/[^A-Za-z0-9]/-/g;
835
836    print "<refentry id=\"$id\">\n";
837    print "<refentryinfo>\n";
838    print " <title>LINUX</title>\n";
839    print " <productname>Kernel Hackers Manual</productname>\n";
840    print " <date>$man_date</date>\n";
841    print "</refentryinfo>\n";
842    print "<refmeta>\n";
843    print " <refentrytitle><phrase>typedef ".$args{'typedef'}."</phrase></refentrytitle>\n";
844    print " <manvolnum>9</manvolnum>\n";
845    print "</refmeta>\n";
846    print "<refnamediv>\n";
847    print " <refname>typedef ".$args{'typedef'}."</refname>\n";
848    print " <refpurpose>\n";
849    print "  ";
850    output_highlight ($args{'purpose'});
851    print " </refpurpose>\n";
852    print "</refnamediv>\n";
853
854    print "<refsynopsisdiv>\n";
855    print " <title>Synopsis</title>\n";
856    print "  <synopsis>typedef ".$args{'typedef'}.";</synopsis>\n";
857    print "</refsynopsisdiv>\n";
858
859    output_section_xml(@_);
860
861    print "</refentry>\n\n";
862}
863
864# output in XML DocBook
865sub output_intro_xml(%) {
866    my %args = %{$_[0]};
867    my ($parameter, $section);
868    my $count;
869
870    my $id = $args{'module'};
871    $id =~ s/[^A-Za-z0-9]/-/g;
872
873    # print out each section
874    $lineprefix="   ";
875    foreach $section (@{$args{'sectionlist'}}) {
876	print "<refsect1>\n <title>$section</title>\n <para>\n";
877	if ($section =~ m/EXAMPLE/i) {
878	    print "<example><para>\n";
879	}
880	output_highlight($args{'sections'}{$section});
881	if ($section =~ m/EXAMPLE/i) {
882	    print "</para></example>\n";
883	}
884	print " </para>\n</refsect1>\n";
885    }
886
887    print "\n\n";
888}
889
890# output in XML DocBook
891sub output_function_gnome {
892    my %args = %{$_[0]};
893    my ($parameter, $section);
894    my $count;
895    my $id;
896
897    $id = $args{'module'}."-".$args{'function'};
898    $id =~ s/[^A-Za-z0-9]/-/g;
899
900    print "<sect2>\n";
901    print " <title id=\"$id\">".$args{'function'}."</title>\n";
902
903    print "  <funcsynopsis>\n";
904    print "   <funcdef>".$args{'functiontype'}." ";
905    print "<function>".$args{'function'}." ";
906    print "</function></funcdef>\n";
907
908    $count = 0;
909    if ($#{$args{'parameterlist'}} >= 0) {
910	foreach $parameter (@{$args{'parameterlist'}}) {
911	    $type = $args{'parametertypes'}{$parameter};
912	    if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
913		# pointer-to-function
914		print "   <paramdef>$1 <parameter>$parameter</parameter>)\n";
915		print "     <funcparams>$2</funcparams></paramdef>\n";
916	    } else {
917		print "   <paramdef>".$type;
918		print " <parameter>$parameter</parameter></paramdef>\n";
919	    }
920	}
921    } else {
922	print "  <void>\n";
923    }
924    print "  </funcsynopsis>\n";
925    if ($#{$args{'parameterlist'}} >= 0) {
926	print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
927	print "<tgroup cols=\"2\">\n";
928	print "<colspec colwidth=\"2*\">\n";
929	print "<colspec colwidth=\"8*\">\n";
930	print "<tbody>\n";
931	foreach $parameter (@{$args{'parameterlist'}}) {
932	    my $parameter_name = $parameter;
933	    $parameter_name =~ s/\[.*//;
934
935	    print "  <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
936	    print "   <entry>\n";
937	    $lineprefix="     ";
938	    output_highlight($args{'parameterdescs'}{$parameter_name});
939	    print "    </entry></row>\n";
940	}
941	print " </tbody></tgroup></informaltable>\n";
942    } else {
943	print " <para>\n  None\n </para>\n";
944    }
945
946    # print out each section
947    $lineprefix="   ";
948    foreach $section (@{$args{'sectionlist'}}) {
949	print "<simplesect>\n <title>$section</title>\n";
950	if ($section =~ m/EXAMPLE/i) {
951	    print "<example><programlisting>\n";
952	} else {
953	}
954	print "<para>\n";
955	output_highlight($args{'sections'}{$section});
956	print "</para>\n";
957	if ($section =~ m/EXAMPLE/i) {
958	    print "</programlisting></example>\n";
959	} else {
960	}
961	print " </simplesect>\n";
962    }
963
964    print "</sect2>\n\n";
965}
966
967##
968# output function in man
969sub output_function_man(%) {
970    my %args = %{$_[0]};
971    my ($parameter, $section);
972    my $count;
973
974    print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
975
976    print ".SH NAME\n";
977    print $args{'function'}." \\- ".$args{'purpose'}."\n";
978
979    print ".SH SYNOPSIS\n";
980    if ($args{'functiontype'} ne "") {
981	print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n";
982    } else {
983	print ".B \"".$args{'function'}."\n";
984    }
985    $count = 0;
986    my $parenth = "(";
987    my $post = ",";
988    foreach my $parameter (@{$args{'parameterlist'}}) {
989	if ($count == $#{$args{'parameterlist'}}) {
990	    $post = ");";
991	}
992	$type = $args{'parametertypes'}{$parameter};
993	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
994	    # pointer-to-function
995	    print ".BI \"".$parenth.$1."\" ".$parameter." \") (".$2.")".$post."\"\n";
996	} else {
997	    $type =~ s/([^\*])$/$1 /;
998	    print ".BI \"".$parenth.$type."\" ".$parameter." \"".$post."\"\n";
999	}
1000	$count++;
1001	$parenth = "";
1002    }
1003
1004    print ".SH ARGUMENTS\n";
1005    foreach $parameter (@{$args{'parameterlist'}}) {
1006	my $parameter_name = $parameter;
1007	$parameter_name =~ s/\[.*//;
1008
1009	print ".IP \"".$parameter."\" 12\n";
1010	output_highlight($args{'parameterdescs'}{$parameter_name});
1011    }
1012    foreach $section (@{$args{'sectionlist'}}) {
1013	print ".SH \"", uc $section, "\"\n";
1014	output_highlight($args{'sections'}{$section});
1015    }
1016}
1017
1018##
1019# output enum in man
1020sub output_enum_man(%) {
1021    my %args = %{$_[0]};
1022    my ($parameter, $section);
1023    my $count;
1024
1025    print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
1026
1027    print ".SH NAME\n";
1028    print "enum ".$args{'enum'}." \\- ".$args{'purpose'}."\n";
1029
1030    print ".SH SYNOPSIS\n";
1031    print "enum ".$args{'enum'}." {\n";
1032    $count = 0;
1033    foreach my $parameter (@{$args{'parameterlist'}}) {
1034	print ".br\n.BI \"    $parameter\"\n";
1035	if ($count == $#{$args{'parameterlist'}}) {
1036	    print "\n};\n";
1037	    last;
1038	}
1039	else {
1040	    print ", \n.br\n";
1041	}
1042	$count++;
1043    }
1044
1045    print ".SH Constants\n";
1046    foreach $parameter (@{$args{'parameterlist'}}) {
1047	my $parameter_name = $parameter;
1048	$parameter_name =~ s/\[.*//;
1049
1050	print ".IP \"".$parameter."\" 12\n";
1051	output_highlight($args{'parameterdescs'}{$parameter_name});
1052    }
1053    foreach $section (@{$args{'sectionlist'}}) {
1054	print ".SH \"$section\"\n";
1055	output_highlight($args{'sections'}{$section});
1056    }
1057}
1058
1059##
1060# output struct in man
1061sub output_struct_man(%) {
1062    my %args = %{$_[0]};
1063    my ($parameter, $section);
1064
1065    print ".TH \"$args{'module'}\" 9 \"".$args{'type'}." ".$args{'struct'}."\" \"$man_date\" \"API Manual\" LINUX\n";
1066
1067    print ".SH NAME\n";
1068    print $args{'type'}." ".$args{'struct'}." \\- ".$args{'purpose'}."\n";
1069
1070    print ".SH SYNOPSIS\n";
1071    print $args{'type'}." ".$args{'struct'}." {\n.br\n";
1072
1073    foreach my $parameter (@{$args{'parameterlist'}}) {
1074	if ($parameter =~ /^#/) {
1075	    print ".BI \"$parameter\"\n.br\n";
1076	    next;
1077	}
1078	my $parameter_name = $parameter;
1079	$parameter_name =~ s/\[.*//;
1080
1081	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1082	$type = $args{'parametertypes'}{$parameter};
1083	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1084	    # pointer-to-function
1085	    print ".BI \"    ".$1."\" ".$parameter." \") (".$2.")"."\"\n;\n";
1086	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1087	    # bitfield
1088	    print ".BI \"    ".$1."\ \" ".$parameter.$2." \""."\"\n;\n";
1089	} else {
1090	    $type =~ s/([^\*])$/$1 /;
1091	    print ".BI \"    ".$type."\" ".$parameter." \""."\"\n;\n";
1092	}
1093	print "\n.br\n";
1094    }
1095    print "};\n.br\n";
1096
1097    print ".SH Members\n";
1098    foreach $parameter (@{$args{'parameterlist'}}) {
1099	($parameter =~ /^#/) && next;
1100
1101	my $parameter_name = $parameter;
1102	$parameter_name =~ s/\[.*//;
1103
1104	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1105	print ".IP \"".$parameter."\" 12\n";
1106	output_highlight($args{'parameterdescs'}{$parameter_name});
1107    }
1108    foreach $section (@{$args{'sectionlist'}}) {
1109	print ".SH \"$section\"\n";
1110	output_highlight($args{'sections'}{$section});
1111    }
1112}
1113
1114##
1115# output typedef in man
1116sub output_typedef_man(%) {
1117    my %args = %{$_[0]};
1118    my ($parameter, $section);
1119
1120    print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
1121
1122    print ".SH NAME\n";
1123    print "typedef ".$args{'typedef'}." \\- ".$args{'purpose'}."\n";
1124
1125    foreach $section (@{$args{'sectionlist'}}) {
1126	print ".SH \"$section\"\n";
1127	output_highlight($args{'sections'}{$section});
1128    }
1129}
1130
1131sub output_intro_man(%) {
1132    my %args = %{$_[0]};
1133    my ($parameter, $section);
1134    my $count;
1135
1136    print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
1137
1138    foreach $section (@{$args{'sectionlist'}}) {
1139	print ".SH \"$section\"\n";
1140	output_highlight($args{'sections'}{$section});
1141    }
1142}
1143
1144##
1145# output in text
1146sub output_function_text(%) {
1147    my %args = %{$_[0]};
1148    my ($parameter, $section);
1149    my $start;
1150
1151    print "Name:\n\n";
1152    print $args{'function'}." - ".$args{'purpose'}."\n";
1153
1154    print "\nSynopsis:\n\n";
1155    if ($args{'functiontype'} ne "") {
1156	$start = $args{'functiontype'}." ".$args{'function'}." (";
1157    } else {
1158	$start = $args{'function'}." (";
1159    }
1160    print $start;
1161
1162    my $count = 0;
1163    foreach my $parameter (@{$args{'parameterlist'}}) {
1164	$type = $args{'parametertypes'}{$parameter};
1165	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1166	    # pointer-to-function
1167	    print $1.$parameter.") (".$2;
1168	} else {
1169	    print $type." ".$parameter;
1170	}
1171	if ($count != $#{$args{'parameterlist'}}) {
1172	    $count++;
1173	    print ",\n";
1174	    print " " x length($start);
1175	} else {
1176	    print ");\n\n";
1177	}
1178    }
1179
1180    print "Arguments:\n\n";
1181    foreach $parameter (@{$args{'parameterlist'}}) {
1182	my $parameter_name = $parameter;
1183	$parameter_name =~ s/\[.*//;
1184
1185	print $parameter."\n\t".$args{'parameterdescs'}{$parameter_name}."\n";
1186    }
1187    output_section_text(@_);
1188}
1189
1190#output sections in text
1191sub output_section_text(%) {
1192    my %args = %{$_[0]};
1193    my $section;
1194
1195    print "\n";
1196    foreach $section (@{$args{'sectionlist'}}) {
1197	print "$section:\n\n";
1198	output_highlight($args{'sections'}{$section});
1199    }
1200    print "\n\n";
1201}
1202
1203# output enum in text
1204sub output_enum_text(%) {
1205    my %args = %{$_[0]};
1206    my ($parameter);
1207    my $count;
1208    print "Enum:\n\n";
1209
1210    print "enum ".$args{'enum'}." - ".$args{'purpose'}."\n\n";
1211    print "enum ".$args{'enum'}." {\n";
1212    $count = 0;
1213    foreach $parameter (@{$args{'parameterlist'}}) {
1214	print "\t$parameter";
1215	if ($count != $#{$args{'parameterlist'}}) {
1216	    $count++;
1217	    print ",";
1218	}
1219	print "\n";
1220    }
1221    print "};\n\n";
1222
1223    print "Constants:\n\n";
1224    foreach $parameter (@{$args{'parameterlist'}}) {
1225	print "$parameter\n\t";
1226	print $args{'parameterdescs'}{$parameter}."\n";
1227    }
1228
1229    output_section_text(@_);
1230}
1231
1232# output typedef in text
1233sub output_typedef_text(%) {
1234    my %args = %{$_[0]};
1235    my ($parameter);
1236    my $count;
1237    print "Typedef:\n\n";
1238
1239    print "typedef ".$args{'typedef'}." - ".$args{'purpose'}."\n";
1240    output_section_text(@_);
1241}
1242
1243# output struct as text
1244sub output_struct_text(%) {
1245    my %args = %{$_[0]};
1246    my ($parameter);
1247
1248    print $args{'type'}." ".$args{'struct'}." - ".$args{'purpose'}."\n\n";
1249    print $args{'type'}." ".$args{'struct'}." {\n";
1250    foreach $parameter (@{$args{'parameterlist'}}) {
1251	if ($parameter =~ /^#/) {
1252	    print "$parameter\n";
1253	    next;
1254	}
1255
1256	my $parameter_name = $parameter;
1257	$parameter_name =~ s/\[.*//;
1258
1259	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1260	$type = $args{'parametertypes'}{$parameter};
1261	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1262	    # pointer-to-function
1263	    print "\t$1 $parameter) ($2);\n";
1264	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1265	    # bitfield
1266	    print "\t$1 $parameter$2;\n";
1267	} else {
1268	    print "\t".$type." ".$parameter.";\n";
1269	}
1270    }
1271    print "};\n\n";
1272
1273    print "Members:\n\n";
1274    foreach $parameter (@{$args{'parameterlist'}}) {
1275	($parameter =~ /^#/) && next;
1276
1277	my $parameter_name = $parameter;
1278	$parameter_name =~ s/\[.*//;
1279
1280	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1281	print "$parameter\n\t";
1282	print $args{'parameterdescs'}{$parameter_name}."\n";
1283    }
1284    print "\n";
1285    output_section_text(@_);
1286}
1287
1288sub output_intro_text(%) {
1289    my %args = %{$_[0]};
1290    my ($parameter, $section);
1291
1292    foreach $section (@{$args{'sectionlist'}}) {
1293	print " $section:\n";
1294	print "    -> ";
1295	output_highlight($args{'sections'}{$section});
1296    }
1297}
1298
1299##
1300# generic output function for all types (function, struct/union, typedef, enum);
1301# calls the generated, variable output_ function name based on
1302# functype and output_mode
1303sub output_declaration {
1304    no strict 'refs';
1305    my $name = shift;
1306    my $functype = shift;
1307    my $func = "output_${functype}_$output_mode";
1308    if (($function_only==0) ||
1309	( $function_only == 1 && defined($function_table{$name})) ||
1310	( $function_only == 2 && !defined($function_table{$name})))
1311    {
1312	&$func(@_);
1313	$section_counter++;
1314    }
1315}
1316
1317##
1318# generic output function - calls the right one based on current output mode.
1319sub output_intro {
1320    no strict 'refs';
1321    my $func = "output_intro_".$output_mode;
1322    &$func(@_);
1323    $section_counter++;
1324}
1325
1326##
1327# takes a declaration (struct, union, enum, typedef) and
1328# invokes the right handler. NOT called for functions.
1329sub dump_declaration($$) {
1330    no strict 'refs';
1331    my ($prototype, $file) = @_;
1332    my $func = "dump_".$decl_type;
1333    &$func(@_);
1334}
1335
1336sub dump_union($$) {
1337    dump_struct(@_);
1338}
1339
1340sub dump_struct($$) {
1341    my $x = shift;
1342    my $file = shift;
1343
1344    if ($x =~/(struct|union)\s+(\w+)\s*{(.*)}/) {
1345	$declaration_name = $2;
1346	my $members = $3;
1347
1348	# ignore embedded structs or unions
1349	$members =~ s/{.*?}//g;
1350
1351	# ignore members marked private:
1352	$members =~ s/\/\*.*?private:.*?public:.*?\*\///gos;
1353	$members =~ s/\/\*.*?private:.*//gos;
1354	# strip comments:
1355	$members =~ s/\/\*.*?\*\///gos;
1356
1357	create_parameterlist($members, ';', $file);
1358
1359	output_declaration($declaration_name,
1360			   'struct',
1361			   {'struct' => $declaration_name,
1362			    'module' => $modulename,
1363			    'parameterlist' => \@parameterlist,
1364			    'parameterdescs' => \%parameterdescs,
1365			    'parametertypes' => \%parametertypes,
1366			    'sectionlist' => \@sectionlist,
1367			    'sections' => \%sections,
1368			    'purpose' => $declaration_purpose,
1369			    'type' => $decl_type
1370			   });
1371    }
1372    else {
1373	print STDERR "Error(${file}:$.): Cannot parse struct or union!\n";
1374	++$errors;
1375    }
1376}
1377
1378sub dump_enum($$) {
1379    my $x = shift;
1380    my $file = shift;
1381
1382    $x =~ s@/\*.*?\*/@@gos;	# strip comments.
1383    if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
1384	$declaration_name = $1;
1385	my $members = $2;
1386
1387	foreach my $arg (split ',', $members) {
1388	    $arg =~ s/^\s*(\w+).*/$1/;
1389	    push @parameterlist, $arg;
1390	    if (!$parameterdescs{$arg}) {
1391		$parameterdescs{$arg} = $undescribed;
1392		print STDERR "Warning(${file}:$.): Enum value '$arg' ".
1393		    "not described in enum '$declaration_name'\n";
1394	    }
1395
1396	}
1397
1398	output_declaration($declaration_name,
1399			   'enum',
1400			   {'enum' => $declaration_name,
1401			    'module' => $modulename,
1402			    'parameterlist' => \@parameterlist,
1403			    'parameterdescs' => \%parameterdescs,
1404			    'sectionlist' => \@sectionlist,
1405			    'sections' => \%sections,
1406			    'purpose' => $declaration_purpose
1407			   });
1408    }
1409    else {
1410	print STDERR "Error(${file}:$.): Cannot parse enum!\n";
1411	++$errors;
1412    }
1413}
1414
1415sub dump_typedef($$) {
1416    my $x = shift;
1417    my $file = shift;
1418
1419    $x =~ s@/\*.*?\*/@@gos;	# strip comments.
1420    while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
1421	$x =~ s/\(*.\)\s*;$/;/;
1422	$x =~ s/\[*.\]\s*;$/;/;
1423    }
1424
1425    if ($x =~ /typedef.*\s+(\w+)\s*;/) {
1426	$declaration_name = $1;
1427
1428	output_declaration($declaration_name,
1429			   'typedef',
1430			   {'typedef' => $declaration_name,
1431			    'module' => $modulename,
1432			    'sectionlist' => \@sectionlist,
1433			    'sections' => \%sections,
1434			    'purpose' => $declaration_purpose
1435			   });
1436    }
1437    else {
1438	print STDERR "Error(${file}:$.): Cannot parse typedef!\n";
1439	++$errors;
1440    }
1441}
1442
1443sub create_parameterlist($$$) {
1444    my $args = shift;
1445    my $splitter = shift;
1446    my $file = shift;
1447    my $type;
1448    my $param;
1449
1450    # temporarily replace commas inside function pointer definition
1451    while ($args =~ /(\([^\),]+),/) {
1452	$args =~ s/(\([^\),]+),/$1#/g;
1453    }
1454
1455    foreach my $arg (split($splitter, $args)) {
1456	# strip comments
1457	$arg =~ s/\/\*.*\*\///;
1458	# strip leading/trailing spaces
1459	$arg =~ s/^\s*//;
1460	$arg =~ s/\s*$//;
1461	$arg =~ s/\s+/ /;
1462
1463	if ($arg =~ /^#/) {
1464	    # Treat preprocessor directive as a typeless variable just to fill
1465	    # corresponding data structures "correctly". Catch it later in
1466	    # output_* subs.
1467	    push_parameter($arg, "", $file);
1468	} elsif ($arg =~ m/\(.*\*/) {
1469	    # pointer-to-function
1470	    $arg =~ tr/#/,/;
1471	    $arg =~ m/[^\(]+\(\*\s*([^\)]+)\)/;
1472	    $param = $1;
1473	    $type = $arg;
1474	    $type =~ s/([^\(]+\(\*)$param/$1/;
1475	    push_parameter($param, $type, $file);
1476	} elsif ($arg) {
1477	    $arg =~ s/\s*:\s*/:/g;
1478	    $arg =~ s/\s*\[/\[/g;
1479
1480	    my @args = split('\s*,\s*', $arg);
1481	    if ($args[0] =~ m/\*/) {
1482		$args[0] =~ s/(\*+)\s*/ $1/;
1483	    }
1484
1485	    my @first_arg;
1486	    if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
1487		    shift @args;
1488		    push(@first_arg, split('\s+', $1));
1489		    push(@first_arg, $2);
1490	    } else {
1491		    @first_arg = split('\s+', shift @args);
1492	    }
1493
1494	    unshift(@args, pop @first_arg);
1495	    $type = join " ", @first_arg;
1496
1497	    foreach $param (@args) {
1498		if ($param =~ m/^(\*+)\s*(.*)/) {
1499		    push_parameter($2, "$type $1", $file);
1500		}
1501		elsif ($param =~ m/(.*?):(\d+)/) {
1502		    push_parameter($1, "$type:$2", $file)
1503		}
1504		else {
1505		    push_parameter($param, $type, $file);
1506		}
1507	    }
1508	}
1509    }
1510}
1511
1512sub push_parameter($$$) {
1513	my $param = shift;
1514	my $type = shift;
1515	my $file = shift;
1516
1517	if (($anon_struct_union == 1) && ($type eq "") &&
1518	    ($param eq "}")) {
1519		return;		# ignore the ending }; from anon. struct/union
1520	}
1521
1522	$anon_struct_union = 0;
1523	my $param_name = $param;
1524	$param_name =~ s/\[.*//;
1525
1526	if ($type eq "" && $param =~ /\.\.\.$/)
1527	{
1528	    $type="";
1529	    $parameterdescs{$param} = "variable arguments";
1530	}
1531	elsif ($type eq "" && ($param eq "" or $param eq "void"))
1532	{
1533	    $type="";
1534	    $param="void";
1535	    $parameterdescs{void} = "no arguments";
1536	}
1537	elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
1538	# handle unnamed (anonymous) union or struct:
1539	{
1540		$type = $param;
1541		$param = "{unnamed_" . $param . "}";
1542		$parameterdescs{$param} = "anonymous\n";
1543		$anon_struct_union = 1;
1544	}
1545
1546	# warn if parameter has no description
1547	# (but ignore ones starting with # as these are not parameters
1548	# but inline preprocessor statements);
1549	# also ignore unnamed structs/unions;
1550	if (!$anon_struct_union) {
1551	if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {
1552
1553	    $parameterdescs{$param_name} = $undescribed;
1554
1555	    if (($type eq 'function') || ($type eq 'enum')) {
1556		print STDERR "Warning(${file}:$.): Function parameter ".
1557		    "or member '$param' not " .
1558		    "described in '$declaration_name'\n";
1559	    }
1560	    print STDERR "Warning(${file}:$.):".
1561			 " No description found for parameter '$param'\n";
1562	    ++$warnings;
1563	}
1564	}
1565
1566	push @parameterlist, $param;
1567	$parametertypes{$param} = $type;
1568}
1569
1570##
1571# takes a function prototype and the name of the current file being
1572# processed and spits out all the details stored in the global
1573# arrays/hashes.
1574sub dump_function($$) {
1575    my $prototype = shift;
1576    my $file = shift;
1577
1578    $prototype =~ s/^static +//;
1579    $prototype =~ s/^extern +//;
1580    $prototype =~ s/^fastcall +//;
1581    $prototype =~ s/^asmlinkage +//;
1582    $prototype =~ s/^inline +//;
1583    $prototype =~ s/^__inline__ +//;
1584    $prototype =~ s/^__inline +//;
1585    $prototype =~ s/^__always_inline +//;
1586    $prototype =~ s/^noinline +//;
1587    $prototype =~ s/__devinit +//;
1588    $prototype =~ s/^#define\s+//; #ak added
1589    $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
1590
1591    # Yes, this truly is vile.  We are looking for:
1592    # 1. Return type (may be nothing if we're looking at a macro)
1593    # 2. Function name
1594    # 3. Function parameters.
1595    #
1596    # All the while we have to watch out for function pointer parameters
1597    # (which IIRC is what the two sections are for), C types (these
1598    # regexps don't even start to express all the possibilities), and
1599    # so on.
1600    #
1601    # If you mess with these regexps, it's a good idea to check that
1602    # the following functions' documentation still comes out right:
1603    # - parport_register_device (function pointer parameters)
1604    # - atomic_set (macro)
1605    # - pci_match_device, __copy_to_user (long return type)
1606
1607    if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1608	$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1609	$prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1610	$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1611	$prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1612	$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1613	$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1614	$prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1615	$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1616	$prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1617	$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1618	$prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1619	$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1620	$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1621	$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1622	$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1623	$prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/)  {
1624	$return_type = $1;
1625	$declaration_name = $2;
1626	my $args = $3;
1627
1628	create_parameterlist($args, ',', $file);
1629    } else {
1630	print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n";
1631	++$errors;
1632	return;
1633    }
1634
1635    output_declaration($declaration_name,
1636		       'function',
1637		       {'function' => $declaration_name,
1638			'module' => $modulename,
1639			'functiontype' => $return_type,
1640			'parameterlist' => \@parameterlist,
1641			'parameterdescs' => \%parameterdescs,
1642			'parametertypes' => \%parametertypes,
1643			'sectionlist' => \@sectionlist,
1644			'sections' => \%sections,
1645			'purpose' => $declaration_purpose
1646		       });
1647}
1648
1649sub process_file($);
1650
1651# Read the file that maps relative names to absolute names for
1652# separate source and object directories and for shadow trees.
1653if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
1654	my ($relname, $absname);
1655	while(<SOURCE_MAP>) {
1656		chop();
1657		($relname, $absname) = (split())[0..1];
1658		$relname =~ s:^/+::;
1659		$source_map{$relname} = $absname;
1660	}
1661	close(SOURCE_MAP);
1662}
1663
1664if ($filelist) {
1665	open(FLIST,"<$filelist") or die "Can't open file list $filelist";
1666	while(<FLIST>) {
1667		chop;
1668		process_file($_);
1669	}
1670}
1671
1672foreach (@ARGV) {
1673    chomp;
1674    process_file($_);
1675}
1676if ($verbose && $errors) {
1677  print STDERR "$errors errors\n";
1678}
1679if ($verbose && $warnings) {
1680  print STDERR "$warnings warnings\n";
1681}
1682
1683exit($errors);
1684
1685sub reset_state {
1686    $function = "";
1687    %constants = ();
1688    %parameterdescs = ();
1689    %parametertypes = ();
1690    @parameterlist = ();
1691    %sections = ();
1692    @sectionlist = ();
1693    $prototype = "";
1694
1695    $state = 0;
1696}
1697
1698sub process_state3_function($$) {
1699    my $x = shift;
1700    my $file = shift;
1701
1702    $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1703
1704    if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#define/)) {
1705	# do nothing
1706    }
1707    elsif ($x =~ /([^\{]*)/) {
1708	$prototype .= $1;
1709    }
1710    if (($x =~ /\{/) || ($x =~ /\#define/) || ($x =~ /;/)) {
1711	$prototype =~ s@/\*.*?\*/@@gos;	# strip comments.
1712	$prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1713	$prototype =~ s@^\s+@@gos; # strip leading spaces
1714	dump_function($prototype,$file);
1715	reset_state();
1716    }
1717}
1718
1719sub process_state3_type($$) {
1720    my $x = shift;
1721    my $file = shift;
1722
1723    $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1724    $x =~ s@^\s+@@gos; # strip leading spaces
1725    $x =~ s@\s+$@@gos; # strip trailing spaces
1726    $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1727
1728    if ($x =~ /^#/) {
1729	# To distinguish preprocessor directive from regular declaration later.
1730	$x .= ";";
1731    }
1732
1733    while (1) {
1734	if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
1735	    $prototype .= $1 . $2;
1736	    ($2 eq '{') && $brcount++;
1737	    ($2 eq '}') && $brcount--;
1738	    if (($2 eq ';') && ($brcount == 0)) {
1739		dump_declaration($prototype,$file);
1740		reset_state();
1741		last;
1742	    }
1743	    $x = $3;
1744	} else {
1745	    $prototype .= $x;
1746	    last;
1747	}
1748    }
1749}
1750
1751# replace <, >, and &
1752sub xml_escape($) {
1753	my $text = shift;
1754	if (($output_mode eq "text") || ($output_mode eq "man")) {
1755		return $text;
1756	}
1757	$text =~ s/\&/\\\\\\amp;/g;
1758	$text =~ s/\</\\\\\\lt;/g;
1759	$text =~ s/\>/\\\\\\gt;/g;
1760	return $text;
1761}
1762
1763sub process_file($) {
1764    my $file;
1765    my $identifier;
1766    my $func;
1767    my $descr;
1768    my $initial_section_counter = $section_counter;
1769
1770    if (defined($ENV{'SRCTREE'})) {
1771	$file = "$ENV{'SRCTREE'}" . "/" . "@_";
1772    }
1773    else {
1774	$file = "@_";
1775    }
1776    if (defined($source_map{$file})) {
1777	$file = $source_map{$file};
1778    }
1779
1780    if (!open(IN,"<$file")) {
1781	print STDERR "Error: Cannot open file $file\n";
1782	++$errors;
1783	return;
1784    }
1785
1786    $section_counter = 0;
1787    while (<IN>) {
1788	if ($state == 0) {
1789	    if (/$doc_start/o) {
1790		$state = 1;		# next line is always the function name
1791		$in_doc_sect = 0;
1792	    }
1793	} elsif ($state == 1) {	# this line is the function name (always)
1794	    if (/$doc_block/o) {
1795		$state = 4;
1796		$contents = "";
1797		if ( $1 eq "" ) {
1798			$section = $section_intro;
1799		} else {
1800			$section = $1;
1801		}
1802	    }
1803	    elsif (/$doc_decl/o) {
1804		$identifier = $1;
1805		if (/\s*([\w\s]+?)\s*-/) {
1806		    $identifier = $1;
1807		}
1808
1809		$state = 2;
1810		if (/-(.*)/) {
1811		    # strip leading/trailing/multiple spaces
1812		    $descr= $1;
1813		    $descr =~ s/^\s*//;
1814		    $descr =~ s/\s*$//;
1815		    $descr =~ s/\s+/ /;
1816		    $declaration_purpose = xml_escape($descr);
1817		} else {
1818		    $declaration_purpose = "";
1819		}
1820		if ($identifier =~ m/^struct/) {
1821		    $decl_type = 'struct';
1822		} elsif ($identifier =~ m/^union/) {
1823		    $decl_type = 'union';
1824		} elsif ($identifier =~ m/^enum/) {
1825		    $decl_type = 'enum';
1826		} elsif ($identifier =~ m/^typedef/) {
1827		    $decl_type = 'typedef';
1828		} else {
1829		    $decl_type = 'function';
1830		}
1831
1832		if ($verbose) {
1833		    print STDERR "Info(${file}:$.): Scanning doc for $identifier\n";
1834		}
1835	    } else {
1836		print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.",
1837		" - I thought it was a doc line\n";
1838		++$warnings;
1839		$state = 0;
1840	    }
1841	} elsif ($state == 2) {	# look for head: lines, and include content
1842	    if (/$doc_sect/o) {
1843		$newsection = $1;
1844		$newcontents = $2;
1845
1846		if ($contents ne "") {
1847		    if (!$in_doc_sect && $verbose) {
1848			print STDERR "Warning(${file}:$.): contents before sections\n";
1849			++$warnings;
1850		    }
1851		    dump_section($section, xml_escape($contents));
1852		    $section = $section_default;
1853		}
1854
1855		$in_doc_sect = 1;
1856		$contents = $newcontents;
1857		if ($contents ne "") {
1858		    while ((substr($contents, 0, 1) eq " ") ||
1859			substr($contents, 0, 1) eq "\t") {
1860			    $contents = substr($contents, 1);
1861		    }
1862		    $contents .= "\n";
1863		}
1864		$section = $newsection;
1865	    } elsif (/$doc_end/) {
1866
1867		if ($contents ne "") {
1868		    dump_section($section, xml_escape($contents));
1869		    $section = $section_default;
1870		    $contents = "";
1871		}
1872
1873		$prototype = "";
1874		$state = 3;
1875		$brcount = 0;
1876#		print STDERR "end of doc comment, looking for prototype\n";
1877	    } elsif (/$doc_content/) {
1878		# miguel-style comment kludge, look for blank lines after
1879		# @parameter line to signify start of description
1880		if ($1 eq "" &&
1881			($section =~ m/^@/ || $section eq $section_context)) {
1882		    dump_section($section, xml_escape($contents));
1883		    $section = $section_default;
1884		    $contents = "";
1885		} else {
1886		    $contents .= $1."\n";
1887		}
1888	    } else {
1889		# i dont know - bad line?  ignore.
1890		print STDERR "Warning(${file}:$.): bad line: $_";
1891		++$warnings;
1892	    }
1893	} elsif ($state == 3) {	# scanning for function '{' (end of prototype)
1894	    if ($decl_type eq 'function') {
1895		process_state3_function($_, $file);
1896	    } else {
1897		process_state3_type($_, $file);
1898	    }
1899	} elsif ($state == 4) {
1900		# Documentation block
1901		if (/$doc_block/) {
1902			dump_section($section, $contents);
1903			output_intro({'sectionlist' => \@sectionlist,
1904				      'sections' => \%sections });
1905			$contents = "";
1906			$function = "";
1907			%constants = ();
1908			%parameterdescs = ();
1909			%parametertypes = ();
1910			@parameterlist = ();
1911			%sections = ();
1912			@sectionlist = ();
1913			$prototype = "";
1914			if ( $1 eq "" ) {
1915				$section = $section_intro;
1916			} else {
1917				$section = $1;
1918			}
1919		}
1920		elsif (/$doc_end/)
1921		{
1922			dump_section($section, $contents);
1923			output_intro({'sectionlist' => \@sectionlist,
1924				      'sections' => \%sections });
1925			$contents = "";
1926			$function = "";
1927			%constants = ();
1928			%parameterdescs = ();
1929			%parametertypes = ();
1930			@parameterlist = ();
1931			%sections = ();
1932			@sectionlist = ();
1933			$prototype = "";
1934			$state = 0;
1935		}
1936		elsif (/$doc_content/)
1937		{
1938			if ( $1 eq "" )
1939			{
1940				$contents .= $blankline;
1941			}
1942			else
1943			{
1944				$contents .= $1 . "\n";
1945			}
1946		}
1947	}
1948    }
1949    if ($initial_section_counter == $section_counter) {
1950	print STDERR "Warning(${file}): no structured comments found\n";
1951	if ($output_mode eq "xml") {
1952	    # The template wants at least one RefEntry here; make one.
1953	    print "<refentry>\n";
1954	    print " <refnamediv>\n";
1955	    print "  <refname>\n";
1956	    print "   ${file}\n";
1957	    print "  </refname>\n";
1958	    print "  <refpurpose>\n";
1959	    print "   Document generation inconsistency\n";
1960	    print "  </refpurpose>\n";
1961	    print " </refnamediv>\n";
1962	    print " <refsect1>\n";
1963	    print "  <title>\n";
1964	    print "   Oops\n";
1965	    print "  </title>\n";
1966	    print "  <warning>\n";
1967	    print "   <para>\n";
1968	    print "    The template for this document tried to insert\n";
1969	    print "    the structured comment from the file\n";
1970	    print "    <filename>${file}</filename> at this point,\n";
1971	    print "    but none was found.\n";
1972	    print "    This dummy section is inserted to allow\n";
1973	    print "    generation to continue.\n";
1974	    print "   </para>\n";
1975	    print "  </warning>\n";
1976	    print " </refsect1>\n";
1977	    print "</refentry>\n";
1978	}
1979    }
1980}
1981