|
|
|
|
@ -137,6 +137,8 @@ use strict; |
|
|
|
|
# should document the "Context:" of the function, e.g. whether the functions |
|
|
|
|
# can be called form interrupts. Unlike other sections you can end it with an |
|
|
|
|
# empty line. |
|
|
|
|
# A non-void function should have a "Return:" section describing the return |
|
|
|
|
# value(s). |
|
|
|
|
# Example-sections should contain the string EXAMPLE so that they are marked |
|
|
|
|
# appropriately in DocBook. |
|
|
|
|
# |
|
|
|
|
@ -245,6 +247,7 @@ my $dohighlight = ""; |
|
|
|
|
|
|
|
|
|
my $verbose = 0; |
|
|
|
|
my $output_mode = "man"; |
|
|
|
|
my $output_preformatted = 0; |
|
|
|
|
my $no_doc_sections = 0; |
|
|
|
|
my %highlights = %highlights_man; |
|
|
|
|
my $blankline = $blankline_man; |
|
|
|
|
@ -254,6 +257,7 @@ my $man_date = ('January', 'February', 'March', 'April', 'May', 'June', |
|
|
|
|
'July', 'August', 'September', 'October', |
|
|
|
|
'November', 'December')[(localtime)[4]] . |
|
|
|
|
" " . ((localtime)[5]+1900); |
|
|
|
|
my $show_not_found = 0; |
|
|
|
|
|
|
|
|
|
# Essentially these are globals. |
|
|
|
|
# They probably want to be tidied up, made more localised or something. |
|
|
|
|
@ -295,9 +299,10 @@ my $doc_special = "\@\%\$\&"; |
|
|
|
|
my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start. |
|
|
|
|
my $doc_end = '\*/'; |
|
|
|
|
my $doc_com = '\s*\*\s*'; |
|
|
|
|
my $doc_com_body = '\s*\* ?'; |
|
|
|
|
my $doc_decl = $doc_com . '(\w+)'; |
|
|
|
|
my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)'; |
|
|
|
|
my $doc_content = $doc_com . '(.*)'; |
|
|
|
|
my $doc_content = $doc_com_body . '(.*)'; |
|
|
|
|
my $doc_block = $doc_com . 'DOC:\s*(.*)?'; |
|
|
|
|
|
|
|
|
|
my %constants; |
|
|
|
|
@ -313,6 +318,7 @@ my $section_default = "Description"; # default section |
|
|
|
|
my $section_intro = "Introduction"; |
|
|
|
|
my $section = $section_default; |
|
|
|
|
my $section_context = "Context"; |
|
|
|
|
my $section_return = "Return"; |
|
|
|
|
|
|
|
|
|
my $undescribed = "-- undescribed --"; |
|
|
|
|
|
|
|
|
|
@ -364,6 +370,8 @@ while ($ARGV[0] =~ m/^-(.*)/) { |
|
|
|
|
usage(); |
|
|
|
|
} elsif ($cmd eq '-no-doc-sections') { |
|
|
|
|
$no_doc_sections = 1; |
|
|
|
|
} elsif ($cmd eq '-show-not-found') { |
|
|
|
|
$show_not_found = 1; |
|
|
|
|
} |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
@ -432,7 +440,7 @@ sub dump_doc_section { |
|
|
|
|
my $contents = join "\n", @_; |
|
|
|
|
|
|
|
|
|
if ($no_doc_sections) { |
|
|
|
|
return; |
|
|
|
|
return; |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
if (($function_only == 0) || |
|
|
|
|
@ -485,8 +493,13 @@ sub output_highlight { |
|
|
|
|
$contents =~ s/\s+$//; |
|
|
|
|
} |
|
|
|
|
foreach $line (split "\n", $contents) { |
|
|
|
|
if (! $output_preformatted) { |
|
|
|
|
$line =~ s/^\s*//; |
|
|
|
|
} |
|
|
|
|
if ($line eq ""){ |
|
|
|
|
print $lineprefix, local_unescape($blankline); |
|
|
|
|
if (! $output_preformatted) { |
|
|
|
|
print $lineprefix, local_unescape($blankline); |
|
|
|
|
} |
|
|
|
|
} else { |
|
|
|
|
$line =~ s/\\\\\\/\&/g; |
|
|
|
|
if ($output_mode eq "man" && substr($line, 0, 1) eq ".") { |
|
|
|
|
@ -902,10 +915,12 @@ sub output_section_xml(%) { |
|
|
|
|
print "<title>$section</title>\n"; |
|
|
|
|
if ($section =~ m/EXAMPLE/i) { |
|
|
|
|
print "<informalexample><programlisting>\n"; |
|
|
|
|
$output_preformatted = 1; |
|
|
|
|
} else { |
|
|
|
|
print "<para>\n"; |
|
|
|
|
} |
|
|
|
|
output_highlight($args{'sections'}{$section}); |
|
|
|
|
$output_preformatted = 0; |
|
|
|
|
if ($section =~ m/EXAMPLE/i) { |
|
|
|
|
print "</programlisting></informalexample>\n"; |
|
|
|
|
} else { |
|
|
|
|
@ -1208,10 +1223,12 @@ sub output_blockhead_xml(%) { |
|
|
|
|
} |
|
|
|
|
if ($section =~ m/EXAMPLE/i) { |
|
|
|
|
print "<example><para>\n"; |
|
|
|
|
$output_preformatted = 1; |
|
|
|
|
} else { |
|
|
|
|
print "<para>\n"; |
|
|
|
|
} |
|
|
|
|
output_highlight($args{'sections'}{$section}); |
|
|
|
|
$output_preformatted = 0; |
|
|
|
|
if ($section =~ m/EXAMPLE/i) { |
|
|
|
|
print "</para></example>\n"; |
|
|
|
|
} else { |
|
|
|
|
@ -1287,10 +1304,12 @@ sub output_function_gnome { |
|
|
|
|
print "<simplesect>\n <title>$section</title>\n"; |
|
|
|
|
if ($section =~ m/EXAMPLE/i) { |
|
|
|
|
print "<example><programlisting>\n"; |
|
|
|
|
$output_preformatted = 1; |
|
|
|
|
} else { |
|
|
|
|
} |
|
|
|
|
print "<para>\n"; |
|
|
|
|
output_highlight($args{'sections'}{$section}); |
|
|
|
|
$output_preformatted = 0; |
|
|
|
|
print "</para>\n"; |
|
|
|
|
if ($section =~ m/EXAMPLE/i) { |
|
|
|
|
print "</programlisting></example>\n"; |
|
|
|
|
@ -1734,7 +1753,7 @@ sub dump_struct($$) { |
|
|
|
|
# strip kmemcheck_bitfield_{begin,end}.*; |
|
|
|
|
$members =~ s/kmemcheck_bitfield_.*?;//gos; |
|
|
|
|
# strip attributes |
|
|
|
|
$members =~ s/__aligned\s*\(\d+\)//gos; |
|
|
|
|
$members =~ s/__aligned\s*\(.+\)//gos; |
|
|
|
|
|
|
|
|
|
create_parameterlist($members, ';', $file); |
|
|
|
|
check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested); |
|
|
|
|
@ -2026,6 +2045,28 @@ sub check_sections($$$$$$) { |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
## |
|
|
|
|
# Checks the section describing the return value of a function. |
|
|
|
|
sub check_return_section { |
|
|
|
|
my $file = shift; |
|
|
|
|
my $declaration_name = shift; |
|
|
|
|
my $return_type = shift; |
|
|
|
|
|
|
|
|
|
# Ignore an empty return type (It's a macro) |
|
|
|
|
# Ignore functions with a "void" return type. (But don't ignore "void *") |
|
|
|
|
if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) { |
|
|
|
|
return; |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
if (!defined($sections{$section_return}) || |
|
|
|
|
$sections{$section_return} eq "") { |
|
|
|
|
print STDERR "Warning(${file}:$.): " . |
|
|
|
|
"No description found for return value of " . |
|
|
|
|
"'$declaration_name'\n"; |
|
|
|
|
++$warnings; |
|
|
|
|
} |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
## |
|
|
|
|
# takes a function prototype and the name of the current file being |
|
|
|
|
# processed and spits out all the details stored in the global |
|
|
|
|
# arrays/hashes. |
|
|
|
|
@ -2041,7 +2082,6 @@ sub dump_function($$) { |
|
|
|
|
$prototype =~ s/^__inline +//; |
|
|
|
|
$prototype =~ s/^__always_inline +//; |
|
|
|
|
$prototype =~ s/^noinline +//; |
|
|
|
|
$prototype =~ s/__devinit +//; |
|
|
|
|
$prototype =~ s/__init +//; |
|
|
|
|
$prototype =~ s/__init_or_module +//; |
|
|
|
|
$prototype =~ s/__must_check +//; |
|
|
|
|
@ -2088,14 +2128,22 @@ sub dump_function($$) { |
|
|
|
|
|
|
|
|
|
create_parameterlist($args, ',', $file); |
|
|
|
|
} else { |
|
|
|
|
print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n"; |
|
|
|
|
++$errors; |
|
|
|
|
print STDERR "Warning(${file}:$.): cannot understand function prototype: '$prototype'\n"; |
|
|
|
|
return; |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
my $prms = join " ", @parameterlist; |
|
|
|
|
check_sections($file, $declaration_name, "function", $sectcheck, $prms, ""); |
|
|
|
|
|
|
|
|
|
# This check emits a lot of warnings at the moment, because many |
|
|
|
|
# functions don't have a 'Return' doc section. So until the number |
|
|
|
|
# of warnings goes sufficiently down, the check is only performed in |
|
|
|
|
# verbose mode. |
|
|
|
|
# TODO: always perform the check. |
|
|
|
|
if ($verbose) { |
|
|
|
|
check_return_section($file, $declaration_name, $return_type); |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
output_declaration($declaration_name, |
|
|
|
|
'function', |
|
|
|
|
{'function' => $declaration_name, |
|
|
|
|
@ -2305,6 +2353,9 @@ sub process_file($) { |
|
|
|
|
|
|
|
|
|
$section_counter = 0; |
|
|
|
|
while (<IN>) { |
|
|
|
|
while (s/\\\s*$//) { |
|
|
|
|
$_ .= <IN>; |
|
|
|
|
} |
|
|
|
|
if ($state == 0) { |
|
|
|
|
if (/$doc_start/o) { |
|
|
|
|
$state = 1; # next line is always the function name |
|
|
|
|
@ -2332,7 +2383,7 @@ sub process_file($) { |
|
|
|
|
$descr= $1; |
|
|
|
|
$descr =~ s/^\s*//; |
|
|
|
|
$descr =~ s/\s*$//; |
|
|
|
|
$descr =~ s/\s+/ /; |
|
|
|
|
$descr =~ s/\s+/ /g; |
|
|
|
|
$declaration_purpose = xml_escape($descr); |
|
|
|
|
$in_purpose = 1; |
|
|
|
|
} else { |
|
|
|
|
@ -2424,9 +2475,7 @@ sub process_file($) { |
|
|
|
|
# Continued declaration purpose |
|
|
|
|
chomp($declaration_purpose); |
|
|
|
|
$declaration_purpose .= " " . xml_escape($1); |
|
|
|
|
} elsif ($section =~ m/^Example/) { |
|
|
|
|
$_ =~ s/^\s*\*//; |
|
|
|
|
$contents .= $_; |
|
|
|
|
$declaration_purpose =~ s/\s+/ /g; |
|
|
|
|
} else { |
|
|
|
|
$contents .= $1 . "\n"; |
|
|
|
|
} |
|
|
|
|
@ -2489,6 +2538,9 @@ sub process_file($) { |
|
|
|
|
} |
|
|
|
|
if ($initial_section_counter == $section_counter) { |
|
|
|
|
print STDERR "Warning(${file}): no structured comments found\n"; |
|
|
|
|
if (($function_only == 1) && ($show_not_found == 1)) { |
|
|
|
|
print STDERR " Was looking for '$_'.\n" for keys %function_table; |
|
|
|
|
} |
|
|
|
|
if ($output_mode eq "xml") { |
|
|
|
|
# The template wants at least one RefEntry here; make one. |
|
|
|
|
print "<refentry>\n"; |
|
|
|
|
|
Masahiro Yamada
10 years ago
committed by
Tom Rini