X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=scripts%2Fkernel-doc;h=a2eaf382aa48501ebffb1009dfec8a75e59cd613;hb=6a77f38946aaee1cd85eeec6cf4229b204c15071;hp=a331dfdb209f258bfb5b88097d8e0433790d852c;hpb=9213980e6a70d8473e0ffd4b39ab5b6caaba9ff5;p=linux-2.6.git

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index a331dfdb2..a2eaf382a 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -105,10 +105,7 @@ use strict;
 # enums and typedefs. Instead of the function name you must write the name 
 # of the declaration;  the struct/union/enum/typedef must always precede 
 # the name. Nesting of declarations is not supported. 
-# Use the argument mechanism to document members or constants. In 
-# structs and unions you must declare one member per declaration 
-# (comma-separated members are not allowed -  the parser does not support 
-# this).
+# Use the argument mechanism to document members or constants.
 # e.g.
 # /**
 #  * struct my_struct - short description
@@ -455,7 +452,14 @@ sub output_struct_html(%) {
     print "<h2>".$args{'type'}." ".$args{'struct'}."</h2>\n";
     print "<b>".$args{'type'}." ".$args{'struct'}."</b> {<br>\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
-        ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
+	if ($parameter =~ /^#/) {
+		print "$parameter<br>\n";
+		next;
+	}
+	my $parameter_name = $parameter;
+	$parameter_name =~ s/\[.*//;
+
+        ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 	$type = $args{'parametertypes'}{$parameter};
 	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 	    # pointer-to-function
@@ -471,10 +475,15 @@ sub output_struct_html(%) {
     print "<h3>Members</h3>\n";
     print "<dl>\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
-        ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
+	($parameter =~ /^#/) && next;
+
+	my $parameter_name = $parameter;
+	$parameter_name =~ s/\[.*//;
+
+        ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 	print "<dt><b>".$parameter."</b>\n";
 	print "<dd>";
-	output_highlight($args{'parameterdescs'}{$parameter});
+	output_highlight($args{'parameterdescs'}{$parameter_name});
     }
     print "</dl>\n";
     output_section_html(@_);
@@ -510,10 +519,13 @@ sub output_function_html(%) {
     print "<h3>Arguments</h3>\n";
     print "<dl>\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
-        ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
+	my $parameter_name = $parameter;
+	$parameter_name =~ s/\[.*//;
+
+        ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 	print "<dt><b>".$parameter."</b>\n";
 	print "<dd>";
-	output_highlight($args{'parameterdescs'}{$parameter});
+	output_highlight($args{'parameterdescs'}{$parameter_name});
     }
     print "</dl>\n";
     output_section_html(@_);
@@ -605,10 +617,13 @@ sub output_function_sgml(%) {
     if ($#{$args{'parameterlist'}} >= 0) {
 	print " <variablelist>\n";
 	foreach $parameter (@{$args{'parameterlist'}}) {
+	    my $parameter_name = $parameter;
+	    $parameter_name =~ s/\[.*//;
+
 	    print "  <varlistentry>\n   <term><parameter>$parameter</parameter></term>\n";
 	    print "   <listitem>\n    <para>\n";
 	    $lineprefix="     ";
-	    output_highlight($args{'parameterdescs'}{$parameter});
+	    output_highlight($args{'parameterdescs'}{$parameter_name});
 	    print "    </para>\n   </listitem>\n  </varlistentry>\n";
 	}
 	print " </variablelist>\n";
@@ -647,12 +662,20 @@ sub output_struct_sgml(%) {
     print "  <programlisting>\n";
     print $args{'type'}." ".$args{'struct'}." {\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
-	defined($args{'parameterdescs'}{$parameter}) || next;
-        ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
+	if ($parameter =~ /^#/) {
+	    print "$parameter\n";
+	    next;
+	}
+
+	my $parameter_name = $parameter;
+	$parameter_name =~ s/\[.*//;
+
+	defined($args{'parameterdescs'}{$parameter_name}) || next;
+        ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 	$type = $args{'parametertypes'}{$parameter};
 	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 	    # pointer-to-function
-	    print "  $1 $parameter ($2);\n";
+	    print "  $1 $parameter) ($2);\n";
 	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
 	    print "  $1 $parameter$2;\n";
 	} else {
@@ -668,12 +691,17 @@ sub output_struct_sgml(%) {
 
     print "  <variablelist>\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
-      defined($args{'parameterdescs'}{$parameter}) || next;
-      ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
+      ($parameter =~ /^#/) && next;
+
+      my $parameter_name = $parameter;
+      $parameter_name =~ s/\[.*//;
+
+      defined($args{'parameterdescs'}{$parameter_name}) || next;
+      ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
       print "    <varlistentry>";
       print "      <term>$parameter</term>\n";
       print "      <listitem><para>\n";
-      output_highlight($args{'parameterdescs'}{$parameter});
+      output_highlight($args{'parameterdescs'}{$parameter_name});
       print "      </para></listitem>\n";
       print "    </varlistentry>\n";
     }
@@ -728,10 +756,13 @@ sub output_enum_sgml(%) {
     print " <title>Constants</title>\n";    
     print "  <variablelist>\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
+      my $parameter_name = $parameter;
+      $parameter_name =~ s/\[.*//;
+
       print "    <varlistentry>";
       print "      <term>$parameter</term>\n";
       print "      <listitem><para>\n";
-      output_highlight($args{'parameterdescs'}{$parameter});
+      output_highlight($args{'parameterdescs'}{$parameter_name});
       print "      </para></listitem>\n";
       print "    </varlistentry>\n";
     }
@@ -842,10 +873,13 @@ sub output_function_gnome {
 	print "<colspec colwidth=\"8*\">\n";
 	print "<tbody>\n";
 	foreach $parameter (@{$args{'parameterlist'}}) {
+	    my $parameter_name = $parameter;
+	    $parameter_name =~ s/\[.*//;
+
 	    print "  <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
 	    print "   <entry>\n";
 	    $lineprefix="     ";
-	    output_highlight($args{'parameterdescs'}{$parameter});
+	    output_highlight($args{'parameterdescs'}{$parameter_name});
 	    print "    </entry></row>\n";
 	}
 	print " </tbody></tgroup></informaltable>\n";
@@ -909,8 +943,11 @@ sub output_function_man(%) {
 
     print ".SH ARGUMENTS\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
+	my $parameter_name = $parameter;
+	$parameter_name =~ s/\[.*//;
+
 	print ".IP \"".$parameter."\" 12\n";
-	output_highlight($args{'parameterdescs'}{$parameter});
+	output_highlight($args{'parameterdescs'}{$parameter_name});
     }
     foreach $section (@{$args{'sectionlist'}}) {
 	print ".SH \"", uc $section, "\"\n";
@@ -947,8 +984,11 @@ sub output_enum_man(%) {
 
     print ".SH Constants\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
+	my $parameter_name = $parameter;
+	$parameter_name =~ s/\[.*//;
+
 	print ".IP \"".$parameter."\" 12\n";
-	output_highlight($args{'parameterdescs'}{$parameter});
+	output_highlight($args{'parameterdescs'}{$parameter_name});
     }
     foreach $section (@{$args{'sectionlist'}}) {
 	print ".SH \"$section\"\n";
@@ -968,11 +1008,17 @@ sub output_struct_man(%) {
     print $args{'type'}." ".$args{'struct'}." \\- ".$args{'purpose'}."\n";
 
     print ".SH SYNOPSIS\n";
-    print $args{'type'}." ".$args{'struct'}." {\n";
+    print $args{'type'}." ".$args{'struct'}." {\n.br\n";
 
     foreach my $parameter (@{$args{'parameterlist'}}) {
-        ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
-	print "\n.br\n";
+	if ($parameter =~ /^#/) {
+	    print ".BI \"$parameter\"\n.br\n";
+	    next;
+	}
+	my $parameter_name = $parameter;
+	$parameter_name =~ s/\[.*//;
+
+        ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 	$type = $args{'parametertypes'}{$parameter};
 	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 	    # pointer-to-function
@@ -989,9 +1035,14 @@ sub output_struct_man(%) {
 
     print ".SH Arguments\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
-        ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
+	($parameter =~ /^#/) && next;
+
+	my $parameter_name = $parameter;
+	$parameter_name =~ s/\[.*//;
+
+        ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 	print ".IP \"".$parameter."\" 12\n";
-	output_highlight($args{'parameterdescs'}{$parameter});
+	output_highlight($args{'parameterdescs'}{$parameter_name});
     }
     foreach $section (@{$args{'sectionlist'}}) {
 	print ".SH \"$section\"\n";
@@ -1058,7 +1109,10 @@ sub output_function_text(%) {
 
     print "Arguments:\n\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
-	print $parameter."\n\t".$args{'parameterdescs'}{$parameter}."\n";
+	my $parameter_name = $parameter;
+	$parameter_name =~ s/\[.*//;
+
+	print $parameter."\n\t".$args{'parameterdescs'}{$parameter_name}."\n";
     }
     output_section_text(@_);
 }
@@ -1123,7 +1177,15 @@ sub output_struct_text(%) {
     print $args{'type'}." ".$args{'struct'}.":\n\n";
     print $args{'type'}." ".$args{'struct'}." {\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
-        ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
+	if ($parameter =~ /^#/) {
+	    print "$parameter\n";
+	    next;
+	}
+
+	my $parameter_name = $parameter;
+	$parameter_name =~ s/\[.*//;
+
+        ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 	$type = $args{'parametertypes'}{$parameter};
 	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 	    # pointer-to-function
@@ -1138,9 +1200,14 @@ sub output_struct_text(%) {
 
     print "Members:\n\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
-        ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
+	($parameter =~ /^#/) && next;
+
+	my $parameter_name = $parameter;
+	$parameter_name =~ s/\[.*//;
+
+        ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 	print "$parameter\n\t";
-	print $args{'parameterdescs'}{$parameter}."\n";
+	print $args{'parameterdescs'}{$parameter_name}."\n";
     }
     print "\n";
     output_section_text(@_);
@@ -1206,7 +1273,7 @@ sub dump_struct($$) {
         my $members = $3;
 
 	# ignore embedded structs or unions
-	$members =~ s/{.*}//g;
+	$members =~ s/{.*?}//g;
 
 	create_parameterlist($members, ';', $file);
 
@@ -1311,33 +1378,57 @@ sub create_parameterlist($$$) {
 	$arg =~ s/\s*$//;
 	$arg =~ s/\s+/ /;
 
-	if ($arg =~ m/\(/) {
+	if ($arg =~ /^#/) {
+	    # Treat preprocessor directive as a typeless variable just to fill
+	    # corresponding data structures "correctly". Catch it later in
+	    # output_* subs.
+	    push_parameter($arg, "", $file);
+	} elsif ($arg =~ m/\(/) {
 	    # pointer-to-function
 	    $arg =~ tr/#/,/;
 	    $arg =~ m/[^\(]+\(\*([^\)]+)\)/;
 	    $param = $1;
 	    $type = $arg;
 	    $type =~ s/([^\(]+\(\*)$param/$1/;
+	    push_parameter($param, $type, $file);
 	} else {
-	    # evil magic to get fixed array parameters to work
-	    $arg =~ s/(.+\s+)(.+)\[.*/$1* $2/;
-	    my @args = split('\s', $arg);
-	
-	    $param = pop @args;
-	    if ($param =~ m/^(\*+)(.*)/) {
-	        $param = $2;
-		push @args, $1;
-	    } 
-	    elsif ($param =~ m/(.*?)\s*:\s*(\d+)/) {
-	        $param = $1;
-	        push @args, ":$2";
+	    $arg =~ s/\s*:\s*/:/g;
+	    $arg =~ s/\s*\[/\[/g;
+
+	    my @args = split('\s*,\s*', $arg);
+	    if ($args[0] =~ m/\*/) {
+		$args[0] =~ s/(\*+)\s*/ $1/;
+	    }
+	    my @first_arg = split('\s+', shift @args);
+	    unshift(@args, pop @first_arg);
+	    $type = join " ", @first_arg;
+
+	    foreach $param (@args) {
+		if ($param =~ m/^(\*+)\s*(.*)/) {
+		    push_parameter($2, "$type $1", $file);
+		}
+		elsif ($param =~ m/(.*?):(\d+)/) {
+		    push_parameter($1, "$type:$2", $file)
+		}
+		else {
+		    push_parameter($param, $type, $file);
+		}
 	    }
-	    $type = join " ", @args;
 	}
+    }
+}
+
+sub push_parameter($$$) {
+	my $param = shift;
+	my $type = shift;
+	my $file = shift;
+
+	my $param_name = $param;
+	$param_name =~ s/\[.*//;
 
 	if ($type eq "" && $param eq "...")
 	{
-	    $type="...";
+	    $type="";
 	    $param="...";
 	    $parameterdescs{"..."} = "variable arguments";
 	}
@@ -1347,8 +1438,8 @@ sub create_parameterlist($$$) {
 	    $param="void";
 	    $parameterdescs{void} = "no arguments";
 	}
-	if (defined $type && $type && !defined $parameterdescs{$param}) {
-	    $parameterdescs{$param} = $undescribed;
+	if (defined $type && $type && !defined $parameterdescs{$param_name}) {
+	    $parameterdescs{$param_name} = $undescribed;
 
 	    if (($type eq 'function') || ($type eq 'enum')) {
 	        print STDERR "Warning(${file}:$.): Function parameter ".
@@ -1362,7 +1453,6 @@ sub create_parameterlist($$$) {
 
 	push @parameterlist, $param;
 	$parametertypes{$param} = $type;
-    }
 }
 
 ##
@@ -1511,6 +1601,10 @@ 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
+    if ($x =~ /^#/) {
+	# To distinguish preprocessor directive from regular declaration later.
+	$x .= ";";
+    }
 
     while (1) {
         if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
@@ -1531,7 +1625,7 @@ sub process_state3_type($$) {
 }
 
 sub process_file($) {
-    my ($file) = @_;
+    my ($file) = "$ENV{'SRCTREE'}@_";
     my $identifier;
     my $func;
     my $initial_section_counter = $section_counter;