X-Git-Url: http://git.samba.org/samba.git/?p=sfrench%2Fcifs-2.6.git;a=blobdiff_plain;f=scripts%2Fkernel-doc;h=1d1401807e95809a43e2b72c84ee17d4be2854e8;hp=e5bf649e516a1d38bb9cc0ebf226b989246d09ac;hb=b22da92f2cf52b3c51dd9a45abb658b1414b0784;hpb=932c37c375cca25175f9b6acee4c75d7a96d985f diff --git a/scripts/kernel-doc b/scripts/kernel-doc index e5bf649e516a..1d1401807e95 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. ## @@ -154,13 +155,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_xml = '\\\amp;((struct\s*)*[_\w]+)'; +my $type_struct_xml = '\\&((struct\s*)*[_\w]+)'; my $type_env = '(\$\w+)'; # Output conversion substitutions. @@ -172,7 +174,9 @@ my %highlights_html = ( $type_constant, "\$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", @@ -390,20 +394,26 @@ sub output_highlight { # confess "output_highlight got called with no args?\n"; # } + if ($output_mode eq "html") { + $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 $@; - if ($output_mode eq "html") { - $contents =~ s/\\\\//; - } # print STDERR "contents af:$contents\n"; foreach $line (split "\n", $contents) { if ($line eq ""){ - print $lineprefix, $blankline; + print $lineprefix, local_unescape($blankline); } else { $line =~ s/\\\\\\/\&/g; - print $lineprefix, $line; + if ($output_mode eq "man" && substr($line, 0, 1) eq ".") { + print "\\&$line"; + } else { + print $lineprefix, $line; + } } print "\n"; } @@ -718,6 +728,7 @@ sub output_struct_xml(%) { # pointer-to-function print " $1 $parameter) ($2);\n"; } elsif ($type =~ m/^(.*?)\s*(:.*)/) { + # bitfield print " $1 $parameter$2;\n"; } else { print " ".$type." ".$parameter.";\n"; @@ -1260,6 +1271,7 @@ sub output_struct_text(%) { # 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"; @@ -1510,8 +1522,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/\[.*//; @@ -1530,16 +1547,16 @@ 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; @@ -1691,6 +1708,8 @@ 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 } @@ -1713,6 +1732,8 @@ 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 .= ";"; @@ -1736,7 +1757,13 @@ sub process_state3_type($$) { } } -# 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")) { @@ -1748,6 +1775,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; @@ -1796,7 +1835,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*$//; @@ -1887,7 +1926,7 @@ sub process_file($) { } elsif ($state == 4) { # Documentation block if (/$doc_block/) { - dump_section($section, $contents); + dump_section($section, xml_escape($contents)); output_intro({'sectionlist' => \@sectionlist, 'sections' => \%sections }); $contents = ""; @@ -1907,7 +1946,7 @@ sub process_file($) { } elsif (/$doc_end/) { - dump_section($section, $contents); + dump_section($section, xml_escape($contents)); output_intro({'sectionlist' => \@sectionlist, 'sections' => \%sections }); $contents = "";