Commit 850622df authored by Randy Dunlap's avatar Randy Dunlap Committed by Linus Torvalds

[PATCH] kernel-doc: warn on malformed function docs.

When the verbose (-v) option is used with scripts/kernel-doc, this option
reports when the kernel-doc format is malformed and apparently contains
function description lines before function parameters.  In these cases, the
kernel-doc script will print something like: Warning(filemap.c:335):
contents before sections

I have fixed the problems in mm/filemap.c and added lots of kernel-doc to
that file (posted to the linux-mm mailing list Mon.  2006-June-12).

The real goal (as requested by Andrew Morton) is to allow the short
function description to be more than one line long.  This patch is both a
kernel-doc checker and a tool en route to that goal.
Signed-off-by: default avatarRandy Dunlap <rdunlap@xenotime.net>
Signed-off-by: default avatarAndrew Morton <akpm@osdl.org>
Signed-off-by: default avatarLinus Torvalds <torvalds@osdl.org>
parent 9c8ef561
...@@ -253,6 +253,7 @@ my $lineprefix=""; ...@@ -253,6 +253,7 @@ my $lineprefix="";
# 3 - scanning prototype. # 3 - scanning prototype.
# 4 - documentation block # 4 - documentation block
my $state; my $state;
my $in_doc_sect;
#declaration types: can be #declaration types: can be
# 'function', 'struct', 'union', 'enum', 'typedef' # 'function', 'struct', 'union', 'enum', 'typedef'
...@@ -1706,6 +1707,7 @@ sub process_file($) { ...@@ -1706,6 +1707,7 @@ sub process_file($) {
if ($state == 0) { if ($state == 0) {
if (/$doc_start/o) { if (/$doc_start/o) {
$state = 1; # next line is always the function name $state = 1; # next line is always the function name
$in_doc_sect = 0;
} }
} elsif ($state == 1) { # this line is the function name (always) } elsif ($state == 1) { # this line is the function name (always)
if (/$doc_block/o) { if (/$doc_block/o) {
...@@ -1756,10 +1758,15 @@ sub process_file($) { ...@@ -1756,10 +1758,15 @@ sub process_file($) {
$newcontents = $2; $newcontents = $2;
if ($contents ne "") { if ($contents ne "") {
if (!$in_doc_sect && $verbose) {
print STDERR "Warning(${file}:$.): contents before sections\n";
++$warnings;
}
dump_section($section, xml_escape($contents)); dump_section($section, xml_escape($contents));
$section = $section_default; $section = $section_default;
} }
$in_doc_sect = 1;
$contents = $newcontents; $contents = $newcontents;
if ($contents ne "") { if ($contents ne "") {
if (substr($contents, 0, 1) eq " ") { if (substr($contents, 0, 1) eq " ") {
......
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