# This is a BitKeeper generated patch for the following project:
# Project Name: Linux kernel tree
# This patch format is intended for GNU patch command version 2.5 or higher.
# This patch includes the following deltas:
# ChangeSet 1.433 -> 1.434
# scripts/kernel-doc 1.9 -> 1.10
#
# The following is the BitKeeper ChangeSet Log
# --------------------------------------------
# 02/07/24 sam@mars.ravnborg.org 1.434
# [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
# --------------------------------------------
#
diff -Nru a/scripts/kernel-doc b/scripts/kernel-doc
--- a/scripts/kernel-doc Wed Jul 24 23:25:55 2002
+++ b/scripts/kernel-doc Wed Jul 24 23:25:55 2002
@@ -233,9 +233,17 @@
# 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 @@
( $function_only == 2 && !defined($function_table{$name})))
{
&$func(@_);
+ $section_counter++;
}
}
@@ -1168,6 +1177,7 @@
no strict 'refs';
my $func = "output_intro_".$output_mode;
&$func(@_);
+ $section_counter++;
}
##
@@ -1195,7 +1205,7 @@
# ignore embedded structs or unions
$members =~ s/{.*}//g;
- create_parameterlist($members, ';');
+ create_parameterlist($members, ';', $file);
output_declaration($declaration_name,
'struct',
@@ -1211,7 +1221,8 @@
});
}
else {
- print STDERR "Cannot parse struct or union!\n";
+ print STDERR "Error(${file}:$.): Cannot parse struct or union!\n";
+ ++$errors;
}
}
@@ -1228,8 +1239,8 @@
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 @@
});
}
else {
- print STDERR "Cannot parse enum!\n";
+ print STDERR "Error(${file}:$.): Cannot parse enum!\n";
+ ++$errors;
}
}
@@ -1272,13 +1284,15 @@
});
}
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 @@
$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 @@
$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 @@
$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_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 @@
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 @@
return;
}
+ $section_counter = 0;
while (<IN>) {
if ($state == 0) {
if (/$doc_start/o) {
@@ -1555,10 +1573,10 @@
}
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 @@
}
} 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 @@
}
}
}
+ 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";
+ }
+ }
}
-
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
This archive was generated by hypermail 2b29 : Tue Jul 30 2002 - 14:00:17 EST