system/linux
system/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux synced 2024-11-05 18:23:50 +00:00
Code Issues Projects Releases Packages Wiki Activity

kernel-doc: allow multi-line declaration purpose descriptions

Browse source 
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>
This commit is contained in:
Johannes Weiner 2009-09-17 19:26:53 -07:00 committed by Linus Torvalds
parent 27f5de7963
commit 6423133bde
2 changed files with 19 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
Documentation/kernel-doc-nano-HOWTO.txt
View file

@ -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

21
scripts/kernel-doc
View file

@ -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";
}