Commit 61bdbc4e authored by Sam Ravnborg's avatar Sam Ravnborg Committed by Linus Torvalds

[PATCH] kernel-doc: Generate valid DocBook syntax [3/9]

Forward port from 2.4, originally by Alan Cox
 o Do not generate empty RefEntry's
 o Improved error reporting
parent 8963f360
......@@ -233,9 +233,17 @@ my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
# CAVEAT EMPTOR! Some of the others I localised may not want to be which
# could cause "use of undefined value" or other bugs.
my ($function, %function_table,%parametertypes,$declaration_purpose);
my ($type,$file,$declaration_name,$return_type);
my ($type,$declaration_name,$return_type);
my ($newsection,$newcontents,$prototype,$filelist, $brcount, %source_map);
# Generated docbook code is inserted in a template at a point where
# docbook v3.1 requires a non-zero sequence of RefEntry's; see:
# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
# We keep track of number of generated entries and generate a dummy
# if needs be to ensure the expanded template can be postprocessed
# into html.
my $section_counter = 0;
my $lineprefix="";
# states
......@@ -1158,6 +1166,7 @@ sub output_declaration {
( $function_only == 2 && !defined($function_table{$name})))
{
&$func(@_);
$section_counter++;
}
}
......@@ -1168,6 +1177,7 @@ sub output_intro {
no strict 'refs';
my $func = "output_intro_".$output_mode;
&$func(@_);
$section_counter++;
}
##
......@@ -1195,7 +1205,7 @@ sub dump_struct($$) {
# ignore embedded structs or unions
$members =~ s/{.*}//g;
create_parameterlist($members, ';');
create_parameterlist($members, ';', $file);
output_declaration($declaration_name,
'struct',
......@@ -1211,7 +1221,8 @@ sub dump_struct($$) {
});
}
else {
print STDERR "Cannot parse struct or union!\n";
print STDERR "Error(${file}:$.): Cannot parse struct or union!\n";
++$errors;
}
}
......@@ -1228,8 +1239,8 @@ sub dump_enum($$) {
push @parameterlist, $arg;
if (!$parameterdescs{$arg}) {
$parameterdescs{$arg} = $undescribed;
print STDERR "Warning($file:$.): Enum value '$arg' ".
"described in enum '$declaration_name'\n";
print STDERR "Warning(${file}:$.): Enum value '$arg' ".
"not described in enum '$declaration_name'\n";
}
}
......@@ -1246,7 +1257,8 @@ sub dump_enum($$) {
});
}
else {
print STDERR "Cannot parse enum!\n";
print STDERR "Error(${file}:$.): Cannot parse enum!\n";
++$errors;
}
}
......@@ -1272,13 +1284,15 @@ sub dump_typedef($$) {
});
}
else {
print STDERR "Cannot parse typedef!\n";
print STDERR "Error(${file}:$.): Cannot parse typedef!\n";
++$errors;
}
}
sub create_parameterlist($$) {
sub create_parameterlist($$$) {
my $args = shift;
my $splitter = shift;
my $file = shift;
my $type;
my $param;
......@@ -1332,7 +1346,7 @@ sub create_parameterlist($$) {
$parameterdescs{$param} = $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";
}
......@@ -1392,9 +1406,9 @@ sub dump_function($$) {
$declaration_name = $2;
my $args = $3;
create_parameterlist($args, ',');
create_parameterlist($args, ',', $file);
} else {
print STDERR "Error($.): cannot understand prototype: '$prototype'\n";
print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n";
++$errors;
return;
}
......@@ -1456,8 +1470,9 @@ sub reset_state {
$state = 0;
}
sub process_state3_function($) {
sub process_state3_function($$) {
my $x = shift;
my $file = shift;
if ($x =~ m#\s*/\*\s+MACDOC\s*#io) {
# do nothing
......@@ -1474,8 +1489,9 @@ sub process_state3_function($) {
}
}
sub process_state3_type($) {
sub process_state3_type($$) {
my $x = shift;
my $file = shift;
$x =~ s@/\*.*?\*/@@gos; # strip comments.
$x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
......@@ -1504,6 +1520,7 @@ sub process_file($) {
my ($file) = @_;
my $identifier;
my $func;
my $initial_section_counter = $section_counter;
if (defined($source_map{$file})) {
$file = $source_map{$file};
......@@ -1515,6 +1532,7 @@ sub process_file($) {
return;
}
$section_counter = 0;
while (<IN>) {
if ($state == 0) {
if (/$doc_start/o) {
......@@ -1555,10 +1573,10 @@ sub process_file($) {
}
if ($verbose) {
print STDERR "Info($.): Scanning doc for $identifier\n";
print STDERR "Info(${file}:$.): Scanning doc for $identifier\n";
}
} else {
print STDERR "WARN($.): Cannot understand $_ on line $.",
print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.",
" - I thought it was a doc line\n";
++$errors;
$state = 0;
......@@ -1612,14 +1630,14 @@ sub process_file($) {
}
} else {
# i dont know - bad line? ignore.
print STDERR "WARNING($.): bad line: $_";
print STDERR "Warning(${file}:$.): bad line: $_";
++$errors;
}
} elsif ($state == 3) { # scanning for function { (end of prototype)
if ($decl_type eq 'function') {
process_state3_function($_);
process_state3_function($_, $file);
} else {
process_state3_type($_);
process_state3_type($_, $file);
}
} elsif ($state == 4) {
# Documentation block
......@@ -1671,5 +1689,35 @@ sub process_file($) {
}
}
}
if ($initial_section_counter == $section_counter) {
print STDERR "Warning(${file}): no structured comments found\n";
if ($output_mode eq "sgml") {
# The template wants at least one RefEntry here; make one.
print "<refentry>\n";
print " <refnamediv>\n";
print " <refname>\n";
print " ${file}\n";
print " </refname>\n";
print " <refpurpose>\n";
print " Document generation inconsistency\n";
print " </refpurpose>\n";
print " </refnamediv>\n";
print " <refsect1>\n";
print " <title>\n";
print " Oops\n";
print " </title>\n";
print " <warning>\n";
print " <para>\n";
print " The template for this document tried to insert\n";
print " the structured comment from the file\n";
print " <filename>${file}</filename> at this point,\n";
print " but none was found.\n";
print " This dummy section is inserted to allow\n";
print " generation to continue.\n";
print " </para>\n";
print " </warning>\n";
print " </refsect1>\n";
print "</refentry>\n";
}
}
}
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment