summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJohannes Weiner <hannes@cmpxchg.org>2009-09-18 06:26:53 +0400
committerLinus Torvalds <torvalds@linux-foundation.org>2009-09-18 20:48:52 +0400
commit6423133bdee0e07d1c2f8411cb3fe676c207ba33 (patch)
treeb50ee9b09359d9556542b08b5b4b1d63ac47bd53
parent27f5de7963f46388932472b660f2f9a86ab58454 (diff)
downloadlinux-6423133bdee0e07d1c2f8411cb3fe676c207ba33.tar.xz
kernel-doc: allow multi-line declaration purpose descriptions
Allow the short description after symbol name and dash in a kernel-doc comment to span multiple lines, e.g. like this: /** * unmap_mapping_range - unmap the portion of all mmaps in the * specified address_space corresponding to the specified * page range in the underlying file. * @mapping: the address space containing mmaps to be unmapped. * ... */ The short description ends with a parameter description, an empty line or the end of the comment block. Signed-off-by: Johannes Weiner <hannes@cmpxchg.org> Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
-rw-r--r--Documentation/kernel-doc-nano-HOWTO.txt4
-rwxr-xr-xscripts/kernel-doc21
2 files changed, 19 insertions, 6 deletions
diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt
index 4d04572b6549..348b9e5e28fc 100644
--- a/Documentation/kernel-doc-nano-HOWTO.txt
+++ b/Documentation/kernel-doc-nano-HOWTO.txt
@@ -66,7 +66,9 @@ Example kernel-doc function comment:
* The longer description can have multiple paragraphs.
*/
-The first line, with the short description, must be on a single line.
+The short description following the subject can span multiple lines
+and ends with an @argument description, an empty line or the end of
+the comment block.
The @argument descriptions must begin on the very next line following
this opening short function description line, with no intervening
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index b52d340d759d..ea9f8a58678f 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1995,6 +1995,7 @@ sub process_file($) {
my $identifier;
my $func;
my $descr;
+ my $in_purpose = 0;
my $initial_section_counter = $section_counter;
if (defined($ENV{'SRCTREE'})) {
@@ -2044,6 +2045,7 @@ sub process_file($) {
$descr =~ s/\s*$//;
$descr =~ s/\s+/ /;
$declaration_purpose = xml_escape($descr);
+ $in_purpose = 1;
} else {
$declaration_purpose = "";
}
@@ -2090,6 +2092,7 @@ sub process_file($) {
}
$in_doc_sect = 1;
+ $in_purpose = 0;
$contents = $newcontents;
if ($contents ne "") {
while ((substr($contents, 0, 1) eq " ") ||
@@ -2119,11 +2122,19 @@ sub process_file($) {
} elsif (/$doc_content/) {
# miguel-style comment kludge, look for blank lines after
# @parameter line to signify start of description
- if ($1 eq "" &&
- ($section =~ m/^@/ || $section eq $section_context)) {
- dump_section($file, $section, xml_escape($contents));
- $section = $section_default;
- $contents = "";
+ if ($1 eq "") {
+ if ($section =~ m/^@/ || $section eq $section_context) {
+ dump_section($file, $section, xml_escape($contents));
+ $section = $section_default;
+ $contents = "";
+ } else {
+ $contents .= "\n";
+ }
+ $in_purpose = 0;
+ } elsif ($in_purpose == 1) {
+ # Continued declaration purpose
+ chomp($declaration_purpose);
+ $declaration_purpose .= " " . xml_escape($1);
} else {
$contents .= $1 . "\n";
}