documentation: convert the Documentation directory to UTF-8

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

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 8be269ffbf9d4f8159ca7a49a589f879a3d38583..a325a0c890dc8e0a49ce4992ca4735ba5b5d1530 100755 (executable)
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -159,7 +159,8 @@ my $warnings = 0;
 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 = '\\\amp;((struct\s*)*[_\w]+)';
 my $type_env = '(\$\w+)';
 
 # Output conversion substitutions.
@@ -168,7 +169,8 @@ my $type_env = '(\$\w+)';
 # these work fairly well
 my %highlights_html = ( $type_constant, "<i>\$1</i>",
                        $type_func, "<b>\$1</b>",
-                       $type_struct, "<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>";
 
@@ -326,12 +328,21 @@ while ($ARGV[0] =~ m/^-(.*)/) {
     }
 }
 
+# get kernel version from env
+sub get_kernel_version() {
+    my $version;
+
+    if (defined($ENV{'KERNELVERSION'})) {
+       $version = $ENV{'KERNELVERSION'};
+    }
+    return $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";
 }
 
@@ -378,13 +389,19 @@ sub output_highlight {
 #      confess "output_highlight got called with no args?\n";
 #   }
 
+#   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 ""){
+       if ($line eq ""){
            print $lineprefix, $blankline;
        } else {
-            $line =~ s/\\\\\\/\&/g;
+           $line =~ s/\\\\\\/\&/g;
            print $lineprefix, $line;
        }
        print "\n";
@@ -414,7 +431,7 @@ sub output_enum_html(%) {
     print "<b>enum ".$args{'enum'}."</b> {<br>\n";
     $count = 0;
     foreach $parameter (@{$args{'parameterlist'}}) {
-        print " <b>".$parameter."</b>";
+       print " <b>".$parameter."</b>";
        if ($count != $#{$args{'parameterlist'}}) {
            $count++;
            print ",\n";
@@ -462,15 +479,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 " <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
+           print "&nbsp; &nbsp; <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
        } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
-           print " <i>$1</i> <b>$parameter</b>$2;<br>\n";
+           # bitfield
+           print "&nbsp; &nbsp; <i>$1</i> <b>$parameter</b>$2;<br>\n";
        } else {
-           print " <i>$type</i> <b>$parameter</b>;<br>\n";
+           print "&nbsp; &nbsp; <i>$type</i> <b>$parameter</b>;<br>\n";
        }
     }
     print "};<br>\n";
@@ -483,7 +501,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 "<dt><b>".$parameter."</b>\n";
        print "<dd>";
        output_highlight($args{'parameterdescs'}{$parameter_name});
@@ -525,7 +543,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 "<dt><b>".$parameter."</b>\n";
        print "<dd>";
        output_highlight($args{'parameterdescs'}{$parameter_name});
@@ -592,6 +610,7 @@ sub output_function_xml(%) {
     print "<refmeta>\n";
     print " <refentrytitle><phrase>".$args{'function'}."</phrase></refentrytitle>\n";
     print " <manvolnum>9</manvolnum>\n";
+    print " <refmiscinfo class=\"version\">" . get_kernel_version() . "</refmiscinfo>\n";
     print "</refmeta>\n";
     print "<refnamediv>\n";
     print " <refname>".$args{'function'}."</refname>\n";
@@ -668,6 +687,7 @@ sub output_struct_xml(%) {
     print "<refmeta>\n";
     print " <refentrytitle><phrase>".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>\n";
     print " <manvolnum>9</manvolnum>\n";
+    print " <refmiscinfo class=\"version\">" . get_kernel_version() . "</refmiscinfo>\n";
     print "</refmeta>\n";
     print "<refnamediv>\n";
     print " <refname>".$args{'type'}." ".$args{'struct'}."</refname>\n";
@@ -691,7 +711,7 @@ 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
@@ -752,6 +772,7 @@ sub output_enum_xml(%) {
     print "<refmeta>\n";
     print " <refentrytitle><phrase>enum ".$args{'enum'}."</phrase></refentrytitle>\n";
     print " <manvolnum>9</manvolnum>\n";
+    print " <refmiscinfo class=\"version\">" . get_kernel_version() . "</refmiscinfo>\n";
     print "</refmeta>\n";
     print "<refnamediv>\n";
     print " <refname>enum ".$args{'enum'}."</refname>\n";
@@ -767,11 +788,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 "};";
@@ -1007,7 +1028,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 +1075,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 +1098,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});
     }
@@ -1187,7 +1208,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,7 +1253,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;
        $type = $args{'parametertypes'}{$parameter};
        if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
            # pointer-to-function
@@ -1252,7 +1273,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";
     }
@@ -1284,7 +1305,7 @@ sub output_declaration {
        ( $function_only == 1 && defined($function_table{$name})) ||
        ( $function_only == 2 && !defined($function_table{$name})))
     {
-        &$func(@_);
+       &$func(@_);
        $section_counter++;
     }
 }
@@ -1317,8 +1338,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 +1366,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 +1377,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 +1403,7 @@ sub dump_enum($$) {
                           });
     }
     else {
-        print STDERR "Error(${file}:$.): Cannot parse enum!\n";
+       print STDERR "Error(${file}:$.): Cannot parse enum!\n";
        ++$errors;
     }
 }
@@ -1393,12 +1414,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 +1431,7 @@ sub dump_typedef($$) {
                           });
     }
     else {
-        print STDERR "Error(${file}:$.): Cannot parse typedef!\n";
+       print STDERR "Error(${file}:$.): Cannot parse typedef!\n";
        ++$errors;
     }
 }
@@ -1424,14 +1445,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 +1477,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;
 
@@ -1514,15 +1544,15 @@ sub push_parameter($$$) {
            $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;
@@ -1664,10 +1694,10 @@ sub process_state3_function($$) {
        # 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);
@@ -1688,17 +1718,17 @@ sub process_state3_type($$) {
     }
 
     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;
        }
@@ -1756,7 +1786,7 @@ sub process_file($) {
                } else {
                        $section = $1;
                }
-            }
+           }
            elsif (/$doc_decl/o) {
                $identifier = $1;
                if (/\s*([\w\s]+?)\s*-/) {
@@ -1849,13 +1879,13 @@ 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/) {
+               if (/$doc_block/) {
                        dump_section($section, $contents);
                        output_intro({'sectionlist' => \@sectionlist,
                                      'sections' => \%sections });
@@ -1873,7 +1903,7 @@ sub process_file($) {
                        } else {
                                $section = $1;
                        }
-                }
+               }
                elsif (/$doc_end/)
                {
                        dump_section($section, $contents);
@@ -1900,8 +1930,8 @@ sub process_file($) {
                        {
                                $contents .= $1 . "\n";
                        }
-               }
-          }
+               }
+       }
     }
     if ($initial_section_counter == $section_counter) {
        print STDERR "Warning(${file}): no structured comments found\n";