Merge branch 'for-2.6.24' of master.kernel.org:/pub/scm/linux/kernel/git/jwboyer...

[sfrench/cifs-2.6.git] / scripts / kernel-doc

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index e5bf649e516a1d38bb9cc0ebf226b989246d09ac..1d1401807e95809a43e2b72c84ee17d4be2854e8 100755 (executable)
--- 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 <twaugh@redhat.com>          ##
 ## Copyright (C) 2001  Simon Huggins                             ##
+## Copyright (C) 2005-2007  Randy Dunlap                         ##
 ##                                                              ##
 ## #define enhancements by Armin Kuster <akuster@mvista.com>    ##
 ## 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 = '\\&amp;((struct\s*)*[_\w]+)';
 my $type_env = '(\$\w+)';
 
 # Output conversion substitutions.
@@ -172,7 +174,9 @@ my %highlights_html = ( $type_constant, "<i>\$1</i>",
                        $type_struct_xml, "<i>\$1</i>",
                        $type_env, "<b><i>\$1</i></b>",
                        $type_param, "<tt><b>\$1</b></tt>" );
-my $blankline_html = "<p>";
+my $local_lt = "\\\\\\\\lt:";
+my $local_gt = "\\\\\\\\gt:";
+my $blankline_html = $local_lt . "p" . $local_gt;      # was "<p>"
 
 # XML, docbook format
 my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
@@ -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;
+       $text =~ s/\\\\\\\\gt:/>/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 = "";