From 05189497d10c715bf41c05fb2fd89aa2cf7602f1 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sun, 25 Jun 2006 05:47:47 -0700 Subject: [PATCH] kernel-doc: drop leading space in sections Drop leading space of kernel-doc section contents. "Section" data (contents) are split from the section header (e.g., Note: below is a section header: * Note: list_empty on entry does not return true after this, the entry is * in an undefined state. ). Currently the data/contents begins with a space and is left that way, which causes it to look bad when printed (in text mode; see example below), so just remove the leading space. Note: list_empty on entry does not return true after this, the entry is in an undefined state. Signed-off-by: Randy Dunlap Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- scripts/kernel-doc | 3 +++ 1 file changed, 3 insertions(+) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 99fe4b7fb2f1..fc0835bf65e2 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1762,6 +1762,9 @@ sub process_file($) { $contents = $newcontents; if ($contents ne "") { + if (substr($contents, 0, 1) eq " ") { + $contents = substr($contents, 1); + } $contents .= "\n"; } $section = $newsection; -- cgit v1.2.3 From 232acbcf5304c29f5bb03b0dddeaefd0f98ef45e Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sun, 25 Jun 2006 05:47:48 -0700 Subject: [PATCH] kernel-doc: script cleanups Fix indentation. Quote a brace '{' so that vi won't be fooled by it. Signed-off-by: Randy Dunlap Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- scripts/kernel-doc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index fc0835bf65e2..21f2f3fee745 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1779,7 +1779,7 @@ sub process_file($) { $prototype = ""; $state = 3; $brcount = 0; -# print STDERR "end of doc comment, looking for prototype\n"; +# print STDERR "end of doc comment, looking for prototype\n"; } elsif (/$doc_content/) { # miguel-style comment kludge, look for blank lines after # @parameter line to signify start of description @@ -1796,7 +1796,7 @@ sub process_file($) { print STDERR "Warning(${file}:$.): bad line: $_"; ++$warnings; } - } elsif ($state == 3) { # scanning for function { (end of prototype) + } elsif ($state == 3) { # scanning for function '{' (end of prototype) if ($decl_type eq 'function') { process_state3_function($_, $file); } else { -- cgit v1.2.3 From 850622dfaf3d62907c96707773e0f8e84b3c0c06 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sun, 25 Jun 2006 05:48:55 -0700 Subject: [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 Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- scripts/kernel-doc | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 21f2f3fee745..351def5c6b8f 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -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 " ") { -- cgit v1.2.3 From ecfb251a95dfca6ca0dba63414e9c91fcbb92335 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sun, 25 Jun 2006 05:49:13 -0700 Subject: [PATCH] kernel-doc: don't use XML escapes in text or man output mode For kernel-doc output modes of text and man, do not use XML escapes for less-than, greater-than, and ampersand characters. I.e., leave the text and man output clean and readable. Signed-off-by: Randy Dunlap Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- scripts/kernel-doc | 3 +++ 1 file changed, 3 insertions(+) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 351def5c6b8f..8bf1e54f14e0 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1674,6 +1674,9 @@ sub process_state3_type($$) { # replace <, >, and & sub xml_escape($) { my $text = shift; + if (($output_mode eq "text") || ($output_mode eq "man")) { + return $text; + } $text =~ s/\&/\\\\\\amp;/g; $text =~ s/\/\\\\\\gt;/g; -- cgit v1.2.3 From c51d3dac321df417d59a47574caa7ab61b30d447 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sun, 25 Jun 2006 05:49:14 -0700 Subject: [PATCH] kernel-doc: use Members for struct fields consistently kernel-doc struct fields should be consistently called "Members", not "Arguments", so switch man-mode output to use "Members" like all of the other formats do. Signed-off-by: Randy Dunlap Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- scripts/kernel-doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 8bf1e54f14e0..00e21297aefe 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1065,7 +1065,7 @@ sub output_struct_man(%) { } print "};\n.br\n"; - print ".SH Arguments\n"; + print ".SH Members\n"; foreach $parameter (@{$args{'parameterlist'}}) { ($parameter =~ /^#/) && next; -- cgit v1.2.3