projects / powerpc.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
kernel-doc: handle arrays with arithmetic expressions as initializers
[powerpc.git] / scripts / kernel-doc
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index f50a70f..c47eb31 100755 (executable)
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -83,7 +83,7 @@ use strict;
 #  * my_function
 #  **/
 #
-# If the Description: header tag is ommitted, then there must be a blank line
+# If the Description: header tag is omitted, then there must be a blank line
 # after the last parameter specification.
 # e.g.
 # /**
@@ -265,7 +265,7 @@ my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
 my $doc_end = '\*/';
 my $doc_com = '\s*\*\s*';
 my $doc_decl = $doc_com.'(\w+)';
-my $doc_sect = $doc_com.'(['.$doc_special.']?[\w ]+):(.*)';
+my $doc_sect = $doc_com.'(['.$doc_special.']?[\w\s]+):(.*)';
 my $doc_content = $doc_com.'(.*)';
 my $doc_block = $doc_com.'DOC:\s*(.*)?';
 
@@ -365,7 +365,7 @@ sub dump_section {
 #  parameterlist => @list of parameters
 #  parameterdescs => %parameter descriptions
 #  sectionlist => @list of sections
-#  sections => %descriont descriptions
+#  sections => %section descriptions
 #
 
 sub output_highlight {
@@ -381,10 +381,10 @@ sub output_highlight {
     eval $dohighlight;
     die $@ if $@;
     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 +414,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";
@@ -452,7 +452,7 @@ sub output_struct_html(%) {
     my %args = %{$_[0]};
     my ($parameter);
 
-    print "<h2>".$args{'type'}." ".$args{'struct'}."</h2>\n";
+    print "<h2>".$args{'type'}." ".$args{'struct'}. " - " .$args{'purpose'}."</h2>\n";
     print "<b>".$args{'type'}." ".$args{'struct'}."</b> {<br>\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
        if ($parameter =~ /^#/) {
@@ -462,7 +462,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;
        $type = $args{'parametertypes'}{$parameter};
        if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
            # pointer-to-function
@@ -483,7 +483,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});
@@ -498,8 +498,8 @@ sub output_function_html(%) {
     my %args = %{$_[0]};
     my ($parameter, $section);
     my $count;
-    print "<h2>Function</h2>\n";
 
+    print "<h2>" .$args{'function'}." - ".$args{'purpose'}."</h2>\n";
     print "<i>".$args{'functiontype'}."</i>\n";
     print "<b>".$args{'function'}."</b>\n";
     print "(";
@@ -525,7 +525,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});
@@ -583,14 +583,14 @@ sub output_function_xml(%) {
     $id = "API-".$args{'function'};
     $id =~ s/[^A-Za-z0-9]/-/g;
 
-    print "<refentry>\n";
+    print "<refentry id=\"$id\">\n";
     print "<refentryinfo>\n";
     print " <title>LINUX</title>\n";
     print " <productname>Kernel Hackers Manual</productname>\n";
     print " <date>$man_date</date>\n";
     print "</refentryinfo>\n";
     print "<refmeta>\n";
-    print " <refentrytitle><phrase id=\"$id\">".$args{'function'}."</phrase></refentrytitle>\n";
+    print " <refentrytitle><phrase>".$args{'function'}."</phrase></refentrytitle>\n";
     print " <manvolnum>9</manvolnum>\n";
     print "</refmeta>\n";
     print "<refnamediv>\n";
@@ -659,14 +659,14 @@ sub output_struct_xml(%) {
     $id = "API-struct-".$args{'struct'};
     $id =~ s/[^A-Za-z0-9]/-/g;
 
-    print "<refentry>\n";
+    print "<refentry id=\"$id\">\n";
     print "<refentryinfo>\n";
     print " <title>LINUX</title>\n";
     print " <productname>Kernel Hackers Manual</productname>\n";
     print " <date>$man_date</date>\n";
     print "</refentryinfo>\n";
     print "<refmeta>\n";
-    print " <refentrytitle><phrase id=\"$id\">".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>\n";
+    print " <refentrytitle><phrase>".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>\n";
     print " <manvolnum>9</manvolnum>\n";
     print "</refmeta>\n";
     print "<refnamediv>\n";
@@ -691,7 +691,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
@@ -743,14 +743,14 @@ sub output_enum_xml(%) {
     $id = "API-enum-".$args{'enum'};
     $id =~ s/[^A-Za-z0-9]/-/g;
 
-    print "<refentry>\n";
+    print "<refentry id=\"$id\">\n";
     print "<refentryinfo>\n";
     print " <title>LINUX</title>\n";
     print " <productname>Kernel Hackers Manual</productname>\n";
     print " <date>$man_date</date>\n";
     print "</refentryinfo>\n";
     print "<refmeta>\n";
-    print " <refentrytitle><phrase id=\"$id\">enum ".$args{'enum'}."</phrase></refentrytitle>\n";
+    print " <refentrytitle><phrase>enum ".$args{'enum'}."</phrase></refentrytitle>\n";
     print " <manvolnum>9</manvolnum>\n";
     print "</refmeta>\n";
     print "<refnamediv>\n";
@@ -767,11 +767,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 "};";
@@ -809,14 +809,14 @@ sub output_typedef_xml(%) {
     $id = "API-typedef-".$args{'typedef'};
     $id =~ s/[^A-Za-z0-9]/-/g;
 
-    print "<refentry>\n";
+    print "<refentry id=\"$id\">\n";
     print "<refentryinfo>\n";
     print " <title>LINUX</title>\n";
     print " <productname>Kernel Hackers Manual</productname>\n";
     print " <date>$man_date</date>\n";
     print "</refentryinfo>\n";
     print "<refmeta>\n";
-    print " <refentrytitle><phrase id=\"$id\">typedef ".$args{'typedef'}."</phrase></refentrytitle>\n";
+    print " <refentrytitle><phrase>typedef ".$args{'typedef'}."</phrase></refentrytitle>\n";
     print " <manvolnum>9</manvolnum>\n";
     print "</refmeta>\n";
     print "<refnamediv>\n";
@@ -953,7 +953,11 @@ sub output_function_man(%) {
     print $args{'function'}." \\- ".$args{'purpose'}."\n";
 
     print ".SH SYNOPSIS\n";
-    print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n";
+    if ($args{'functiontype'} ne "") {
+       print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n";
+    } else {
+       print ".B \"".$args{'function'}."\n";
+    }
     $count = 0;
     my $parenth = "(";
     my $post = ",";
@@ -1003,7 +1007,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;
@@ -1050,7 +1054,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
@@ -1073,7 +1077,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});
     }
@@ -1118,13 +1122,19 @@ sub output_intro_man(%) {
 sub output_function_text(%) {
     my %args = %{$_[0]};
     my ($parameter, $section);
+    my $start;
 
     print "Name:\n\n";
     print $args{'function'}." - ".$args{'purpose'}."\n";
 
     print "\nSynopsis:\n\n";
-    my $start=$args{'functiontype'}." ".$args{'function'}." (";
+    if ($args{'functiontype'} ne "") {
+       $start = $args{'functiontype'}." ".$args{'function'}." (";
+    } else {
+       $start = $args{'function'}." (";
+    }
     print $start;
+
     my $count = 0;
     foreach my $parameter (@{$args{'parameterlist'}}) {
        $type = $args{'parametertypes'}{$parameter};
@@ -1177,7 +1187,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 ",";
@@ -1222,7 +1232,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
@@ -1242,7 +1252,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";
     }
@@ -1274,7 +1284,7 @@ sub output_declaration {
        ( $function_only == 1 && defined($function_table{$name})) ||
        ( $function_only == 2 && !defined($function_table{$name})))
     {
-        &$func(@_);
+       &$func(@_);
        $section_counter++;
     }
 }
@@ -1307,8 +1317,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;
@@ -1335,7 +1345,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;
     }
 }
@@ -1346,15 +1356,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";
            }
 
@@ -1372,7 +1382,7 @@ sub dump_enum($$) {
                           });
     }
     else {
-        print STDERR "Error(${file}:$.): Cannot parse enum!\n";
+       print STDERR "Error(${file}:$.): Cannot parse enum!\n";
        ++$errors;
     }
 }
@@ -1383,12 +1393,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',
@@ -1400,7 +1410,7 @@ sub dump_typedef($$) {
                           });
     }
     else {
-        print STDERR "Error(${file}:$.): Cannot parse typedef!\n";
+       print STDERR "Error(${file}:$.): Cannot parse typedef!\n";
        ++$errors;
     }
 }
@@ -1414,14 +1424,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+/ /;
 
@@ -1433,7 +1443,7 @@ sub create_parameterlist($$$) {
        } elsif ($arg =~ m/\(.*\*/) {
            # pointer-to-function
            $arg =~ tr/#/,/;
-           $arg =~ m/[^\(]+\(\*([^\)]+)\)/;
+           $arg =~ m/[^\(]+\(\*\s*([^\)]+)\)/;
            $param = $1;
            $type = $arg;
            $type =~ s/([^\(]+\(\*)$param/$1/;
@@ -1446,7 +1456,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;
 
@@ -1504,15 +1523,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;
@@ -1536,8 +1555,8 @@ sub dump_function($$) {
     $prototype =~ s/^__always_inline +//;
     $prototype =~ s/^noinline +//;
     $prototype =~ s/__devinit +//;
-    $prototype =~ s/^#define +//; #ak added
-    $prototype =~ s/__attribute__ \(\([a-z,]*\)\)//;
+    $prototype =~ s/^#define\s+//; #ak added
+    $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)
@@ -1570,7 +1589,8 @@ sub dump_function($$) {
        $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/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
-       $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/)  {
+       $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
+       $prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/)  {
        $return_type = $1;
        $declaration_name = $2;
        my $args = $3;
@@ -1653,10 +1673,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);
@@ -1677,17 +1697,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;
        }
@@ -1710,6 +1730,7 @@ sub process_file($) {
     my $file;
     my $identifier;
     my $func;
+    my $descr;
     my $initial_section_counter = $section_counter;
 
     if (defined($ENV{'SRCTREE'})) {
@@ -1744,7 +1765,7 @@ sub process_file($) {
                } else {
                        $section = $1;
                }
-            }
+           }
            elsif (/$doc_decl/o) {
                $identifier = $1;
                if (/\s*([\w\s]+?)\s*-/) {
@@ -1753,7 +1774,12 @@ sub process_file($) {
 
                $state = 2;
                if (/-(.*)/) {
-                   $declaration_purpose = xml_escape($1);
+                   # strip leading/trailing/multiple spaces #RDD:T:
+                   $descr= $1;
+                   $descr =~ s/^\s*//;
+                   $descr =~ s/\s*$//;
+                   $descr =~ s/\s+/ /;
+                   $declaration_purpose = xml_escape($descr);
                } else {
                    $declaration_purpose = "";
                }
@@ -1832,13 +1858,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 });
@@ -1856,7 +1882,7 @@ sub process_file($) {
                        } else {
                                $section = $1;
                        }
-                }
+               }
                elsif (/$doc_end/)
                {
                        dump_section($section, $contents);
@@ -1883,8 +1909,8 @@ sub process_file($) {
                        {
                                $contents .= $1 . "\n";
                        }
-               }
-          }
+               }
+       }
     }
     if ($initial_section_counter == $section_counter) {
        print STDERR "Warning(${file}): no structured comments found\n";
DSM-G600 Linux 2.6