Merge to Fedora kernel-2.6.18-1.2224_FC5 patched with stable patch-2.6.18.1-vs2.0...

[linux-2.6.git] / scripts / kernel-doc

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 99fe4b7..c9ca0c2 100755 (executable)
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -253,6 +253,7 @@ my $lineprefix="";
 # 3 - scanning prototype.
 # 4 - documentation block
 my $state;
+my $in_doc_sect;
 
 #declaration types: can be
 # 'function', 'struct', 'union', 'enum', 'typedef'
@@ -1055,7 +1056,8 @@ sub output_struct_man(%) {
            # 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";
@@ -1064,7 +1066,7 @@ sub output_struct_man(%) {
     }
     print "};\n.br\n";
 
-    print ".SH Arguments\n";
+    print ".SH Members\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
        ($parameter =~ /^#/) && next;
 
@@ -1117,7 +1119,10 @@ sub output_function_text(%) {
     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;
@@ -1168,6 +1173,7 @@ sub output_enum_text(%) {
     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'}}) {
@@ -1196,7 +1202,7 @@ sub output_typedef_text(%) {
     my $count;
     print "Typedef:\n\n";
 
-    print "typedef ".$args{'typedef'}."\n";
+    print "typedef ".$args{'typedef'}." - ".$args{'purpose'}."\n";
     output_section_text(@_);
 }
 
@@ -1205,7 +1211,7 @@ sub output_struct_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 =~ /^#/) {
@@ -1512,6 +1518,7 @@ sub dump_function($$) {
     $prototype =~ s/^asmlinkage +//;
     $prototype =~ s/^inline +//;
     $prototype =~ s/^__inline__ +//;
+    $prototype =~ s/__devinit +//;
     $prototype =~ s/^#define +//; #ak added
     $prototype =~ s/__attribute__ \(\([a-z,]*\)\)//;
 
@@ -1673,6 +1680,9 @@ sub process_state3_type($$) {
 # 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;
@@ -1706,6 +1716,7 @@ sub process_file($) {
        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) {
@@ -1756,12 +1767,20 @@ sub process_file($) {
                $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 "") {
+                   if (substr($contents, 0, 1) eq " ") {
+                       $contents = substr($contents, 1);
+                   }
                    $contents .= "\n";
                }
                $section = $newsection;
@@ -1776,7 +1795,7 @@ sub process_file($) {
                $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
@@ -1793,7 +1812,7 @@ sub process_file($) {
                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 {