Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 6423133b authored by Johannes Weiner's avatar Johannes Weiner Committed by Linus Torvalds
Browse files

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: default avatarJohannes Weiner <hannes@cmpxchg.org>
Signed-off-by: default avatarRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
parent 27f5de79

Documentation/kernel-doc-nano-HOWTO.txt

+3 −1
Original line number Diff line number Diff line
@@ -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

scripts/kernel-doc

+16 −5
Original line number Diff line number Diff line
@@ -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)) {

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

		}