X-Git-Url: http://pilppa.org/gitweb/gitweb.cgi?a=blobdiff_plain;f=scripts%2Fkernel-doc;h=26146cbaa504dcf698fd8b4cfe89cb5902029b6a;hb=b23c9cc0ce652089a2f0af8c7f1541f10dc9b5db;hp=4d928b859845d02ba63cf128c7165bc4896b0fac;hpb=902b236c087bf021c94cc21a2b09d928c4156c2b;p=linux-2.6-omap-h63xx.git diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 4d928b85984..26146cbaa50 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -5,6 +5,7 @@ use strict; ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ## ## Copyright (C) 2000, 1 Tim Waugh ## ## Copyright (C) 2001 Simon Huggins ## +## Copyright (C) 2005-2007 Randy Dunlap ## ## ## ## #define enhancements by Armin Kuster ## ## Copyright (c) 2000 MontaVista Software, Inc. ## @@ -45,21 +46,24 @@ use strict; # Note: This only supports 'c'. # usage: -# kernel-doc [ -docbook | -html | -text | -man ] +# kernel-doc [ -docbook | -html | -text | -man ] [ -no-doc-sections ] # [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile # or # [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile # # Set output format using one of -docbook -html -text or -man. Default is man. # +# -no-doc-sections +# Do not output DOC: sections +# # -function funcname -# If set, then only generate documentation for the given function(s). All -# other functions are ignored. +# If set, then only generate documentation for the given function(s) or +# DOC: section titles. All other functions and DOC: sections are ignored. # # -nofunction funcname -# 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)) +# If set, then only generate documentation for the other function(s)/DOC: +# sections. 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 # @@ -154,12 +158,14 @@ use strict; my $errors = 0; my $warnings = 0; +my $anon_struct_union = 0; # match expressions used to find embedded type information my $type_constant = '\%([-_\w]+)'; my $type_func = '(\w+)\(\)'; my $type_param = '\@(\w+)'; -my $type_struct = '\&((struct\s*)?[_\w]+)'; +my $type_struct = '\&((struct\s*)*[_\w]+)'; +my $type_struct_xml = '\\&((struct\s*)*[_\w]+)'; my $type_env = '(\$\w+)'; # Output conversion substitutions. @@ -168,18 +174,21 @@ my $type_env = '(\$\w+)'; # these work fairly well my %highlights_html = ( $type_constant, "\$1", $type_func, "\$1", - $type_struct, "\$1", + $type_struct_xml, "\$1", + $type_env, "\$1", $type_param, "\$1" ); -my $blankline_html = "

"; +my $local_lt = "\\\\\\\\lt:"; +my $local_gt = "\\\\\\\\gt:"; +my $blankline_html = $local_lt . "p" . $local_gt; # was "

" # XML, docbook format my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1\$2", $type_constant, "\$1", $type_func, "\$1", - $type_struct, "\$1", + $type_struct_xml, "\$1", $type_env, "\$1", $type_param, "\$1" ); -my $blankline_xml = "\n"; +my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n"; # gnome, docbook format my %highlights_gnome = ( $type_constant, "\$1", @@ -205,10 +214,11 @@ my $blankline_text = ""; sub usage { - print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ]\n"; + print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ] [ -no-doc-sections ]\n"; print " [ -function funcname [ -function funcname ...] ]\n"; print " [ -nofunction funcname [ -nofunction funcname ...] ]\n"; print " c source file(s) > outputfile\n"; + print " -v : verbose output, more warnings & other info listed\n"; exit 1; } @@ -219,6 +229,7 @@ if ($#ARGV==-1) { my $verbose = 0; my $output_mode = "man"; +my $no_doc_sections = 0; my %highlights = %highlights_man; my $blankline = $blankline_man; my $modulename = "Kernel API"; @@ -323,15 +334,27 @@ while ($ARGV[0] =~ m/^-(.*)/) { usage(); } elsif ($cmd eq '-filelist') { $filelist = shift @ARGV; + } elsif ($cmd eq '-no-doc-sections') { + $no_doc_sections = 1; } } +# get kernel version from env +sub get_kernel_version() { + my $version = 'unknown kernel version'; + + if (defined($ENV{'KERNELVERSION'})) { + $version = $ENV{'KERNELVERSION'}; + } + return $version; +} +my $kernelversion = get_kernel_version(); # generate a sequence of code that will splice in highlighting information # using the s// operator. my $dohighlight = ""; foreach my $pattern (keys %highlights) { -# print "scanning pattern $pattern ($highlights{$pattern})\n"; +# print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n"; $dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n"; } @@ -357,6 +380,29 @@ sub dump_section { } } +## +# dump DOC: section after checking that it should go out +# +sub dump_doc_section { + my $name = shift; + my $contents = join "\n", @_; + + if ($no_doc_sections) { + return; + } + + if (($function_only == 0) || + ( $function_only == 1 && defined($function_table{$name})) || + ( $function_only == 2 && !defined($function_table{$name}))) + { + dump_section $name, $contents; + output_blockhead({'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'module' => $modulename, + 'content-only' => ($function_only != 0), }); + } +} + ## # output function # @@ -378,14 +424,26 @@ sub output_highlight { # confess "output_highlight got called with no args?\n"; # } + if ($output_mode eq "html" || $output_mode eq "xml") { + $contents = local_unescape($contents); + # convert data read & converted thru xml_escape() into &xyz; format: + $contents =~ s/\\\\\\/&/g; + } +# print STDERR "contents b4:$contents\n"; eval $dohighlight; die $@ if $@; +# print STDERR "contents af:$contents\n"; + foreach $line (split "\n", $contents) { - if ($line eq ""){ - print $lineprefix, $blankline; + if ($line eq ""){ + print $lineprefix, local_unescape($blankline); } else { - $line =~ s/\\\\\\/\&/g; - print $lineprefix, $line; + $line =~ s/\\\\\\/\&/g; + if ($output_mode eq "man" && substr($line, 0, 1) eq ".") { + print "\\&$line"; + } else { + print $lineprefix, $line; + } } print "\n"; } @@ -414,7 +472,7 @@ sub output_enum_html(%) { print "enum ".$args{'enum'}." {
\n"; $count = 0; foreach $parameter (@{$args{'parameterlist'}}) { - print " ".$parameter.""; + print " ".$parameter.""; if ($count != $#{$args{'parameterlist'}}) { $count++; print ",\n"; @@ -452,7 +510,7 @@ sub output_struct_html(%) { my %args = %{$_[0]}; my ($parameter); - print "

".$args{'type'}." ".$args{'struct'}."

\n"; + print "

".$args{'type'}." ".$args{'struct'}. " - " .$args{'purpose'}."

\n"; print "".$args{'type'}." ".$args{'struct'}." {
\n"; foreach $parameter (@{$args{'parameterlist'}}) { if ($parameter =~ /^#/) { @@ -462,15 +520,16 @@ sub output_struct_html(%) { my $parameter_name = $parameter; $parameter_name =~ s/\[.*//; - ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; $type = $args{'parametertypes'}{$parameter}; if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { # pointer-to-function - print " $1$parameter) ($2);
\n"; + print "    $1$parameter) ($2);
\n"; } elsif ($type =~ m/^(.*?)\s*(:.*)/) { - print " $1 $parameter$2;
\n"; + # bitfield + print "    $1 $parameter$2;
\n"; } else { - print " $type $parameter;
\n"; + print "    $type $parameter;
\n"; } } print "};
\n"; @@ -483,7 +542,7 @@ sub output_struct_html(%) { my $parameter_name = $parameter; $parameter_name =~ s/\[.*//; - ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; print "
".$parameter."\n"; print "
"; output_highlight($args{'parameterdescs'}{$parameter_name}); @@ -498,8 +557,8 @@ sub output_function_html(%) { my %args = %{$_[0]}; my ($parameter, $section); my $count; - print "

Function

\n"; + print "

" .$args{'function'}." - ".$args{'purpose'}."

\n"; print "".$args{'functiontype'}."\n"; print "".$args{'function'}."\n"; print "("; @@ -525,7 +584,7 @@ sub output_function_html(%) { my $parameter_name = $parameter; $parameter_name =~ s/\[.*//; - ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; print "
".$parameter."\n"; print "
"; output_highlight($args{'parameterdescs'}{$parameter_name}); @@ -535,8 +594,8 @@ sub output_function_html(%) { print "
\n"; } -# output intro in html -sub output_intro_html(%) { +# output DOC: block header in html +sub output_blockhead_html(%) { my %args = %{$_[0]}; my ($parameter, $section); my $count; @@ -592,6 +651,7 @@ sub output_function_xml(%) { print "\n"; print " ".$args{'function'}."\n"; print " 9\n"; + print " " . $kernelversion . "\n"; print "\n"; print "\n"; print " ".$args{'function'}."\n"; @@ -668,6 +728,7 @@ sub output_struct_xml(%) { print "\n"; print " ".$args{'type'}." ".$args{'struct'}."\n"; print " 9\n"; + print " " . $kernelversion . "\n"; print "\n"; print "\n"; print " ".$args{'type'}." ".$args{'struct'}."\n"; @@ -691,12 +752,13 @@ sub output_struct_xml(%) { $parameter_name =~ s/\[.*//; defined($args{'parameterdescs'}{$parameter_name}) || next; - ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; $type = $args{'parametertypes'}{$parameter}; if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { # pointer-to-function print " $1 $parameter) ($2);\n"; } elsif ($type =~ m/^(.*?)\s*(:.*)/) { + # bitfield print " $1 $parameter$2;\n"; } else { print " ".$type." ".$parameter.";\n"; @@ -752,6 +814,7 @@ sub output_enum_xml(%) { print "\n"; print " enum ".$args{'enum'}."\n"; print " 9\n"; + print " " . $kernelversion . "\n"; print "\n"; print "\n"; print " enum ".$args{'enum'}."\n"; @@ -767,11 +830,11 @@ sub output_enum_xml(%) { print "enum ".$args{'enum'}." {\n"; $count = 0; foreach $parameter (@{$args{'parameterlist'}}) { - print " $parameter"; - if ($count != $#{$args{'parameterlist'}}) { + print " $parameter"; + if ($count != $#{$args{'parameterlist'}}) { $count++; print ","; - } + } print "\n"; } print "};"; @@ -838,7 +901,7 @@ sub output_typedef_xml(%) { } # output in XML DocBook -sub output_intro_xml(%) { +sub output_blockhead_xml(%) { my %args = %{$_[0]}; my ($parameter, $section); my $count; @@ -849,15 +912,23 @@ sub output_intro_xml(%) { # print out each section $lineprefix=" "; foreach $section (@{$args{'sectionlist'}}) { - print "\n $section\n \n"; + if (!$args{'content-only'}) { + print "\n $section\n"; + } if ($section =~ m/EXAMPLE/i) { print "\n"; + } else { + print "\n"; } output_highlight($args{'sections'}{$section}); if ($section =~ m/EXAMPLE/i) { print "\n"; + } else { + print ""; + } + if (!$args{'content-only'}) { + print "\n\n"; } - print " \n\n"; } print "\n\n"; @@ -1007,7 +1078,7 @@ sub output_enum_man(%) { print "enum ".$args{'enum'}." {\n"; $count = 0; foreach my $parameter (@{$args{'parameterlist'}}) { - print ".br\n.BI \" $parameter\"\n"; + print ".br\n.BI \" $parameter\"\n"; if ($count == $#{$args{'parameterlist'}}) { print "\n};\n"; last; @@ -1054,7 +1125,7 @@ sub output_struct_man(%) { my $parameter_name = $parameter; $parameter_name =~ s/\[.*//; - ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; $type = $args{'parametertypes'}{$parameter}; if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { # pointer-to-function @@ -1077,7 +1148,7 @@ sub output_struct_man(%) { my $parameter_name = $parameter; $parameter_name =~ s/\[.*//; - ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; print ".IP \"".$parameter."\" 12\n"; output_highlight($args{'parameterdescs'}{$parameter_name}); } @@ -1104,7 +1175,7 @@ sub output_typedef_man(%) { } } -sub output_intro_man(%) { +sub output_blockhead_man(%) { my %args = %{$_[0]}; my ($parameter, $section); my $count; @@ -1187,7 +1258,7 @@ sub output_enum_text(%) { print "enum ".$args{'enum'}." {\n"; $count = 0; foreach $parameter (@{$args{'parameterlist'}}) { - print "\t$parameter"; + print "\t$parameter"; if ($count != $#{$args{'parameterlist'}}) { $count++; print ","; @@ -1232,12 +1303,13 @@ sub output_struct_text(%) { my $parameter_name = $parameter; $parameter_name =~ s/\[.*//; - ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; $type = $args{'parametertypes'}{$parameter}; if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { # pointer-to-function print "\t$1 $parameter) ($2);\n"; } elsif ($type =~ m/^(.*?)\s*(:.*)/) { + # bitfield print "\t$1 $parameter$2;\n"; } else { print "\t".$type." ".$parameter.";\n"; @@ -1252,7 +1324,7 @@ sub output_struct_text(%) { my $parameter_name = $parameter; $parameter_name =~ s/\[.*//; - ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; print "$parameter\n\t"; print $args{'parameterdescs'}{$parameter_name}."\n"; } @@ -1260,7 +1332,7 @@ sub output_struct_text(%) { output_section_text(@_); } -sub output_intro_text(%) { +sub output_blockhead_text(%) { my %args = %{$_[0]}; my ($parameter, $section); @@ -1284,16 +1356,16 @@ sub output_declaration { ( $function_only == 1 && defined($function_table{$name})) || ( $function_only == 2 && !defined($function_table{$name}))) { - &$func(@_); + &$func(@_); $section_counter++; } } ## # generic output function - calls the right one based on current output mode. -sub output_intro { +sub output_blockhead { no strict 'refs'; - my $func = "output_intro_".$output_mode; + my $func = "output_blockhead_".$output_mode; &$func(@_); $section_counter++; } @@ -1317,8 +1389,8 @@ sub dump_struct($$) { my $file = shift; if ($x =~/(struct|union)\s+(\w+)\s*{(.*)}/) { - $declaration_name = $2; - my $members = $3; + $declaration_name = $2; + my $members = $3; # ignore embedded structs or unions $members =~ s/{.*?}//g; @@ -1345,7 +1417,7 @@ sub dump_struct($$) { }); } else { - print STDERR "Error(${file}:$.): Cannot parse struct or union!\n"; + print STDERR "Error(${file}:$.): Cannot parse struct or union!\n"; ++$errors; } } @@ -1356,15 +1428,15 @@ sub dump_enum($$) { $x =~ s@/\*.*?\*/@@gos; # strip comments. if ($x =~ /enum\s+(\w+)\s*{(.*)}/) { - $declaration_name = $1; - my $members = $2; + $declaration_name = $1; + my $members = $2; foreach my $arg (split ',', $members) { $arg =~ s/^\s*(\w+).*/$1/; push @parameterlist, $arg; if (!$parameterdescs{$arg}) { - $parameterdescs{$arg} = $undescribed; - print STDERR "Warning(${file}:$.): Enum value '$arg' ". + $parameterdescs{$arg} = $undescribed; + print STDERR "Warning(${file}:$.): Enum value '$arg' ". "not described in enum '$declaration_name'\n"; } @@ -1382,7 +1454,7 @@ sub dump_enum($$) { }); } else { - print STDERR "Error(${file}:$.): Cannot parse enum!\n"; + print STDERR "Error(${file}:$.): Cannot parse enum!\n"; ++$errors; } } @@ -1393,12 +1465,12 @@ sub dump_typedef($$) { $x =~ s@/\*.*?\*/@@gos; # strip comments. while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) { - $x =~ s/\(*.\)\s*;$/;/; + $x =~ s/\(*.\)\s*;$/;/; $x =~ s/\[*.\]\s*;$/;/; } if ($x =~ /typedef.*\s+(\w+)\s*;/) { - $declaration_name = $1; + $declaration_name = $1; output_declaration($declaration_name, 'typedef', @@ -1410,7 +1482,7 @@ sub dump_typedef($$) { }); } else { - print STDERR "Error(${file}:$.): Cannot parse typedef!\n"; + print STDERR "Error(${file}:$.): Cannot parse typedef!\n"; ++$errors; } } @@ -1424,14 +1496,14 @@ sub create_parameterlist($$$) { # temporarily replace commas inside function pointer definition while ($args =~ /(\([^\),]+),/) { - $args =~ s/(\([^\),]+),/$1#/g; + $args =~ s/(\([^\),]+),/$1#/g; } foreach my $arg (split($splitter, $args)) { # strip comments $arg =~ s/\/\*.*\*\///; - # strip leading/trailing spaces - $arg =~ s/^\s*//; + # strip leading/trailing spaces + $arg =~ s/^\s*//; $arg =~ s/\s*$//; $arg =~ s/\s+/ /; @@ -1456,7 +1528,16 @@ sub create_parameterlist($$$) { if ($args[0] =~ m/\*/) { $args[0] =~ s/(\*+)\s*/ $1/; } - my @first_arg = split('\s+', shift @args); + + my @first_arg; + if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) { + shift @args; + push(@first_arg, split('\s+', $1)); + push(@first_arg, $2); + } else { + @first_arg = split('\s+', shift @args); + } + unshift(@args, pop @first_arg); $type = join " ", @first_arg; @@ -1479,8 +1560,13 @@ sub push_parameter($$$) { my $param = shift; my $type = shift; my $file = shift; - my $anon = 0; + if (($anon_struct_union == 1) && ($type eq "") && + ($param eq "}")) { + return; # ignore the ending }; from anon. struct/union + } + + $anon_struct_union = 0; my $param_name = $param; $param_name =~ s/\[.*//; @@ -1499,30 +1585,30 @@ sub push_parameter($$$) { # handle unnamed (anonymous) union or struct: { $type = $param; - $param = "{unnamed_" . $param. "}"; + $param = "{unnamed_" . $param . "}"; $parameterdescs{$param} = "anonymous\n"; - $anon = 1; + $anon_struct_union = 1; } # warn if parameter has no description # (but ignore ones starting with # as these are not parameters # but inline preprocessor statements); # also ignore unnamed structs/unions; - if (!$anon) { + if (!$anon_struct_union) { if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) { $parameterdescs{$param_name} = $undescribed; if (($type eq 'function') || ($type eq 'enum')) { - print STDERR "Warning(${file}:$.): Function parameter ". + print STDERR "Warning(${file}:$.): Function parameter ". "or member '$param' not " . "described in '$declaration_name'\n"; } print STDERR "Warning(${file}:$.):". - " No description found for parameter '$param'\n"; + " No description found for parameter '$param'\n"; ++$warnings; - } - } + } + } push @parameterlist, $param; $parametertypes{$param} = $type; @@ -1538,7 +1624,6 @@ sub dump_function($$) { $prototype =~ s/^static +//; $prototype =~ s/^extern +//; - $prototype =~ s/^fastcall +//; $prototype =~ s/^asmlinkage +//; $prototype =~ s/^inline +//; $prototype =~ s/^__inline__ +//; @@ -1547,7 +1632,7 @@ sub dump_function($$) { $prototype =~ s/^noinline +//; $prototype =~ s/__devinit +//; $prototype =~ s/^#define\s+//; #ak added - $prototype =~ s/__attribute__ \(\([a-z,]*\)\)//; + $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//; # Yes, this truly is vile. We are looking for: # 1. Return type (may be nothing if we're looking at a macro) @@ -1569,7 +1654,7 @@ sub dump_function($$) { $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || - $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || @@ -1660,14 +1745,16 @@ sub process_state3_function($$) { my $x = shift; my $file = shift; + $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line + if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#define/)) { # do nothing } elsif ($x =~ /([^\{]*)/) { - $prototype .= $1; + $prototype .= $1; } if (($x =~ /\{/) || ($x =~ /\#define/) || ($x =~ /;/)) { - $prototype =~ s@/\*.*?\*/@@gos; # strip comments. + $prototype =~ s@/\*.*?\*/@@gos; # strip comments. $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's. $prototype =~ s@^\s+@@gos; # strip leading spaces dump_function($prototype,$file); @@ -1682,30 +1769,38 @@ sub process_state3_type($$) { $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's. $x =~ s@^\s+@@gos; # strip leading spaces $x =~ s@\s+$@@gos; # strip trailing spaces + $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line + if ($x =~ /^#/) { # To distinguish preprocessor directive from regular declaration later. $x .= ";"; } while (1) { - if ( $x =~ /([^{};]*)([{};])(.*)/ ) { + if ( $x =~ /([^{};]*)([{};])(.*)/ ) { $prototype .= $1 . $2; ($2 eq '{') && $brcount++; ($2 eq '}') && $brcount--; if (($2 eq ';') && ($brcount == 0)) { - dump_declaration($prototype,$file); + dump_declaration($prototype,$file); reset_state(); - last; + last; } $x = $3; - } else { + } else { $prototype .= $x; last; } } } -# replace <, >, and & +# xml_escape: replace <, >, and & in the text stream; +# +# however, formatting controls that are generated internally/locally in the +# kernel-doc script are not escaped here; instead, they begin life like +# $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings +# are converted to their mnemonic-expected output, without the 4 * '\' & ':', +# just before actual output; (this is done by local_unescape()) sub xml_escape($) { my $text = shift; if (($output_mode eq "text") || ($output_mode eq "man")) { @@ -1717,6 +1812,18 @@ sub xml_escape($) { return $text; } +# convert local escape strings to html +# local escape strings look like: '\\\\menmonic:' (that's 4 backslashes) +sub local_unescape($) { + my $text = shift; + if (($output_mode eq "text") || ($output_mode eq "man")) { + return $text; + } + $text =~ s/\\\\\\\\lt://g; + return $text; +} + sub process_file($) { my $file; my $identifier; @@ -1756,7 +1863,7 @@ sub process_file($) { } else { $section = $1; } - } + } elsif (/$doc_decl/o) { $identifier = $1; if (/\s*([\w\s]+?)\s*-/) { @@ -1765,7 +1872,7 @@ sub process_file($) { $state = 2; if (/-(.*)/) { - # strip leading/trailing/multiple spaces #RDD:T: + # strip leading/trailing/multiple spaces $descr= $1; $descr =~ s/^\s*//; $descr =~ s/\s*$//; @@ -1774,6 +1881,13 @@ sub process_file($) { } else { $declaration_purpose = ""; } + + if (($declaration_purpose eq "") && $verbose) { + print STDERR "Warning(${file}:$.): missing initial short description on line:\n"; + print STDERR $_; + ++$warnings; + } + if ($identifier =~ m/^struct/) { $decl_type = 'struct'; } elsif ($identifier =~ m/^union/) { @@ -1800,7 +1914,7 @@ sub process_file($) { $newsection = $1; $newcontents = $2; - if ($contents ne "") { + if (($contents ne "") && ($contents ne "\n")) { if (!$in_doc_sect && $verbose) { print STDERR "Warning(${file}:$.): contents before sections\n"; ++$warnings; @@ -1849,16 +1963,14 @@ sub process_file($) { } } elsif ($state == 3) { # scanning for function '{' (end of prototype) if ($decl_type eq 'function') { - process_state3_function($_, $file); + process_state3_function($_, $file); } else { - process_state3_type($_, $file); + process_state3_type($_, $file); } } elsif ($state == 4) { # Documentation block - if (/$doc_block/) { - dump_section($section, $contents); - output_intro({'sectionlist' => \@sectionlist, - 'sections' => \%sections }); + if (/$doc_block/) { + dump_doc_section($section, xml_escape($contents)); $contents = ""; $function = ""; %constants = (); @@ -1873,12 +1985,10 @@ sub process_file($) { } else { $section = $1; } - } + } elsif (/$doc_end/) { - dump_section($section, $contents); - output_intro({'sectionlist' => \@sectionlist, - 'sections' => \%sections }); + dump_doc_section($section, xml_escape($contents)); $contents = ""; $function = ""; %constants = (); @@ -1900,8 +2010,8 @@ sub process_file($) { { $contents .= $1 . "\n"; } - } - } + } + } } if ($initial_section_counter == $section_counter) { print STDERR "Warning(${file}): no structured comments found\n";