dect
/
linux-2.6
Archived
13
0
Fork 0
Code Releases Activity

[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: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
This commit is contained in:
Randy Dunlap 2006-06-25 05:48:55 -07:00 committed by Linus Torvalds
parent 9c8ef5614d
commit 850622dfaf
1 changed files with 7 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
scripts/kernel-doc
View File

@ -253,6 +253,7 @@ my $lineprefix="";
# 3 - scanning prototype.
# 4 - documentation block
my $state;
my $in_doc_sect;
#declaration types: can be
# 'function', 'struct', 'union', 'enum', 'typedef'
@ -1706,6 +1707,7 @@ sub process_file($) {
if ($state == 0) {
if (/$doc_start/o) {
$state = 1; # next line is always the function name
$in_doc_sect = 0;
}
} elsif ($state == 1) { # this line is the function name (always)
if (/$doc_block/o) {
@ -1756,10 +1758,15 @@ sub process_file($) {
$newcontents = $2;
if ($contents ne "") {
if (!$in_doc_sect && $verbose) {
print STDERR "Warning(${file}:$.): contents before sections\n";
++$warnings;
}
dump_section($section, xml_escape($contents));
$section = $section_default;
}
$in_doc_sect = 1;
$contents = $newcontents;
if ($contents ne "") {
if (substr($contents, 0, 1) eq " ") {