# other functions are ignored.
#
# -nofunction funcname
-# If set, then only generate documentation for the other function(s). All
-# other functions are ignored. Cannot be used with -function together
+# If set, then only generate documentation for the other function(s).
+# Cannot be used together with -function
# (yes, that's a bug -- perl hackers can fix it 8))
#
# c files - list of 'c' files to process
# 3 - scanning prototype.
# 4 - documentation block
my $state;
+my $in_doc_sect;
#declaration types: can be
# 'function', 'struct', 'union', 'enum', 'typedef'
# pointer-to-function
print ".BI \" ".$1."\" ".$parameter." \") (".$2.")"."\"\n;\n";
} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
- print ".BI \" ".$1."\" ".$parameter.$2." \""."\"\n;\n";
+ # bitfield
+ print ".BI \" ".$1."\ \" ".$parameter.$2." \""."\"\n;\n";
} else {
$type =~ s/([^\*])$/$1 /;
print ".BI \" ".$type."\" ".$parameter." \""."\"\n;\n";
}
print "};\n.br\n";
- print ".SH Arguments\n";
+ print ".SH Members\n";
foreach $parameter (@{$args{'parameterlist'}}) {
($parameter =~ /^#/) && next;
my %args = %{$_[0]};
my ($parameter, $section);
- print "Function:\n\n";
+ print "Name:\n\n";
+ print $args{'function'}." - ".$args{'purpose'}."\n";
+
+ print "\nSynopsis:\n\n";
my $start=$args{'functiontype'}." ".$args{'function'}." (";
print $start;
my $count = 0;
my $count;
print "Enum:\n\n";
+ print "enum ".$args{'enum'}." - ".$args{'purpose'}."\n\n";
print "enum ".$args{'enum'}." {\n";
$count = 0;
foreach $parameter (@{$args{'parameterlist'}}) {
my $count;
print "Typedef:\n\n";
- print "typedef ".$args{'typedef'}."\n";
+ print "typedef ".$args{'typedef'}." - ".$args{'purpose'}."\n";
output_section_text(@_);
}
my %args = %{$_[0]};
my ($parameter);
- print $args{'type'}." ".$args{'struct'}.":\n\n";
+ print $args{'type'}." ".$args{'struct'}." - ".$args{'purpose'}."\n\n";
print $args{'type'}." ".$args{'struct'}." {\n";
foreach $parameter (@{$args{'parameterlist'}}) {
if ($parameter =~ /^#/) {
}
##
-# generic output function for typedefs
+# generic output function for all types (function, struct/union, typedef, enum);
+# calls the generated, variable output_ function name based on
+# functype and output_mode
sub output_declaration {
no strict 'refs';
my $name = shift;
}
##
-# generic output function - calls the right one based
-# on current output mode.
+# generic output function - calls the right one based on current output mode.
sub output_intro {
no strict 'refs';
my $func = "output_intro_".$output_mode;
# corresponding data structures "correctly". Catch it later in
# output_* subs.
push_parameter($arg, "", $file);
- } elsif ($arg =~ m/\(/) {
+ } elsif ($arg =~ m/\(.*\*/) {
# pointer-to-function
$arg =~ tr/#/,/;
$arg =~ m/[^\(]+\(\*([^\)]+)\)/;
my $param = shift;
my $type = shift;
my $file = shift;
+ my $anon = 0;
my $param_name = $param;
$param_name =~ s/\[.*//;
$param="void";
$parameterdescs{void} = "no arguments";
}
+ elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
+ # handle unnamed (anonymous) union or struct:
+ {
+ $type = $param;
+ $param = "{unnamed_" . $param. "}";
+ $parameterdescs{$param} = "anonymous\n";
+ $anon = 1;
+ }
+
# warn if parameter has no description
- # (but ignore ones starting with # as these are no parameters
- # but inline preprocessor statements
+ # (but ignore ones starting with # as these are not parameters
+ # but inline preprocessor statements);
+ # also ignore unnamed structs/unions;
+ if (!$anon) {
if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {
$parameterdescs{$param_name} = $undescribed;
" No description found for parameter '$param'\n";
++$warnings;
}
+ }
push @parameterlist, $param;
$parametertypes{$param} = $type;
$prototype =~ s/^asmlinkage +//;
$prototype =~ s/^inline +//;
$prototype =~ s/^__inline__ +//;
+ $prototype =~ s/^__inline +//;
+ $prototype =~ s/^__always_inline +//;
+ $prototype =~ s/^noinline +//;
+ $prototype =~ s/__devinit +//;
$prototype =~ s/^#define +//; #ak added
$prototype =~ s/__attribute__ \(\([a-z,]*\)\)//;
# replace <, >, and &
sub xml_escape($) {
my $text = shift;
+ if (($output_mode eq "text") || ($output_mode eq "man")) {
+ return $text;
+ }
$text =~ s/\&/\\\\\\amp;/g;
$text =~ s/\</\\\\\\lt;/g;
$text =~ s/\>/\\\\\\gt;/g;
if ($state == 0) {
if (/$doc_start/o) {
$state = 1; # next line is always the function name
+ $in_doc_sect = 0;
}
} elsif ($state == 1) { # this line is the function name (always)
if (/$doc_block/o) {
$newcontents = $2;
if ($contents ne "") {
+ if (!$in_doc_sect && $verbose) {
+ print STDERR "Warning(${file}:$.): contents before sections\n";
+ ++$warnings;
+ }
dump_section($section, xml_escape($contents));
$section = $section_default;
}
+ $in_doc_sect = 1;
$contents = $newcontents;
if ($contents ne "") {
+ while ((substr($contents, 0, 1) eq " ") ||
+ substr($contents, 0, 1) eq "\t") {
+ $contents = substr($contents, 1);
+ }
$contents .= "\n";
}
$section = $newsection;
$prototype = "";
$state = 3;
$brcount = 0;
-# print STDERR "end of doc comment, looking for prototype\n";
+# print STDERR "end of doc comment, looking for prototype\n";
} elsif (/$doc_content/) {
# miguel-style comment kludge, look for blank lines after
# @parameter line to signify start of description
print STDERR "Warning(${file}:$.): bad line: $_";
++$warnings;
}
- } elsif ($state == 3) { # scanning for function { (end of prototype)
+ } elsif ($state == 3) { # scanning for function '{' (end of prototype)
if ($decl_type eq 'function') {
process_state3_function($_, $file);
} else {