X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=scripts%2Fkernel-doc;h=a2eaf382aa48501ebffb1009dfec8a75e59cd613;hb=6a77f38946aaee1cd85eeec6cf4229b204c15071;hp=945a28bdedbd70cde414e1daeac573383ac514f7;hpb=5273a3df6485dc2ad6aa7ddd441b9a21970f003b;p=linux-2.6.git
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 945a28bde..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 "
".$args{'type'}." ".$args{'struct'}."
\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
@@ -471,10 +475,15 @@ sub output_struct_html(%) {
print "Members
\n";
print "\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";
print "
- ";
- output_highlight($args{'parameterdescs'}{$parameter});
+ output_highlight($args{'parameterdescs'}{$parameter_name});
}
print "
\n";
output_section_html(@_);
@@ -510,10 +519,13 @@ sub output_function_html(%) {
print "Arguments
\n";
print "\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 "- ".$parameter."\n";
print "
- ";
- output_highlight($args{'parameterdescs'}{$parameter});
+ output_highlight($args{'parameterdescs'}{$parameter_name});
}
print "
\n";
output_section_html(@_);
@@ -605,10 +617,13 @@ sub output_function_sgml(%) {
if ($#{$args{'parameterlist'}} >= 0) {
print " \n";
foreach $parameter (@{$args{'parameterlist'}}) {
+ my $parameter_name = $parameter;
+ $parameter_name =~ s/\[.*//;
+
print " \n $parameter\n";
print " \n \n";
$lineprefix=" ";
- output_highlight($args{'parameterdescs'}{$parameter});
+ output_highlight($args{'parameterdescs'}{$parameter_name});
print " \n \n \n";
}
print " \n";
@@ -647,12 +662,20 @@ sub output_struct_sgml(%) {
print " \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 " \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 " ";
print " $parameter\n";
print " \n";
- output_highlight($args{'parameterdescs'}{$parameter});
+ output_highlight($args{'parameterdescs'}{$parameter_name});
print " \n";
print " \n";
}
@@ -728,10 +756,13 @@ sub output_enum_sgml(%) {
print " Constants\n";
print " \n";
foreach $parameter (@{$args{'parameterlist'}}) {
+ my $parameter_name = $parameter;
+ $parameter_name =~ s/\[.*//;
+
print " ";
print " $parameter\n";
print " \n";
- output_highlight($args{'parameterdescs'}{$parameter});
+ output_highlight($args{'parameterdescs'}{$parameter_name});
print " \n";
print " \n";
}
@@ -842,10 +873,13 @@ sub output_function_gnome {
print "\n";
print "\n";
foreach $parameter (@{$args{'parameterlist'}}) {
+ my $parameter_name = $parameter;
+ $parameter_name =~ s/\[.*//;
+
print " $parameter\n";
print " \n";
$lineprefix=" ";
- output_highlight($args{'parameterdescs'}{$parameter});
+ output_highlight($args{'parameterdescs'}{$parameter_name});
print "
\n";
}
print " \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);
@@ -1304,38 +1371,64 @@ sub create_parameterlist($$$) {
}
foreach my $arg (split($splitter, $args)) {
+ # strip comments
+ $arg =~ s/\/\*.*\*\///;
# strip leading/trailing spaces
$arg =~ s/^\s*//;
$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";
}
@@ -1345,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 ".
@@ -1360,7 +1453,6 @@ sub create_parameterlist($$$) {
push @parameterlist, $param;
$parametertypes{$param} = $type;
- }
}
##
@@ -1509,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 =~ /([^{};]*)([{};])(.*)/ ) {
@@ -1529,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;