diff options
Diffstat (limited to 'scripts/kernel-doc')
| -rwxr-xr-x | scripts/kernel-doc | 141 |
1 files changed, 86 insertions, 55 deletions
diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 8be269ffbf9..e5bf649e516 100755 --- 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,22 @@ while ($ARGV[0] =~ m/^-(.*)/) { } } +# get kernel version from env +sub get_kernel_version() { + my $version; + + if (defined($ENV{'KERNELVERSION'})) { + $version = $ENV{'KERNELVERSION'}; + } + return $version; +} +my $kernelversion = get_kernel_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 +390,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 +432,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 +480,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 " <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 " <i>$1</i> <b>$parameter</b>$2;<br>\n"; } else { - print " <i>$type</i> <b>$parameter</b>;<br>\n"; + print " <i>$type</i> <b>$parameter</b>;<br>\n"; } } print "};<br>\n"; @@ -483,7 +502,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 +544,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 +611,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\">" . $kernelversion . "</refmiscinfo>\n"; print "</refmeta>\n"; print "<refnamediv>\n"; print " <refname>".$args{'function'}."</refname>\n"; @@ -668,6 +688,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\">" . $kernelversion . "</refmiscinfo>\n"; print "</refmeta>\n"; print "<refnamediv>\n"; print " <refname>".$args{'type'}." ".$args{'struct'}."</refname>\n"; @@ -691,7 +712,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 +773,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\">" . $kernelversion . "</refmiscinfo>\n"; print "</refmeta>\n"; print "<refnamediv>\n"; print " <refname>enum ".$args{'enum'}."</refname>\n"; @@ -767,11 +789,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 +1029,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 +1076,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 +1099,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 +1209,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 +1254,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 +1274,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 +1306,7 @@ sub output_declaration { ( $function_only == 1 && defined($function_table{$name})) || ( $function_only == 2 && !defined($function_table{$name}))) { - &$func(@_); + &$func(@_); $section_counter++; } } @@ -1317,8 +1339,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 +1367,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 +1378,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 +1404,7 @@ sub dump_enum($$) { }); } else { - print STDERR "Error(${file}:$.): Cannot parse enum!\n"; + print STDERR "Error(${file}:$.): Cannot parse enum!\n"; ++$errors; } } @@ -1393,12 +1415,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 +1432,7 @@ sub dump_typedef($$) { }); } else { - print STDERR "Error(${file}:$.): Cannot parse typedef!\n"; + print STDERR "Error(${file}:$.): Cannot parse typedef!\n"; ++$errors; } } @@ -1424,14 +1446,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 +1478,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 +1545,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 +1695,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 +1719,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 +1787,7 @@ sub process_file($) { } else { $section = $1; } - } + } elsif (/$doc_decl/o) { $identifier = $1; if (/\s*([\w\s]+?)\s*-/) { @@ -1849,13 +1880,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 +1904,7 @@ sub process_file($) { } else { $section = $1; } - } + } elsif (/$doc_end/) { dump_section($section, $contents); @@ -1900,8 +1931,8 @@ sub process_file($) { { $contents .= $1 . "\n"; } - } - } + } + } } if ($initial_section_counter == $section_counter) { print STDERR "Warning(${file}): no structured comments found\n"; |