Commit 0d55d48b authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet
Browse files

scripts: kernel-doc: accept blank lines on parameter description 



Sphinx is very pedantic with respect to blank lines. Sometimes,
in order to make it to properly handle something, we need to
add a blank line. However, currently, any blank line inside a
kernel-doc comment like:

	/*
	 * @foo: bar
         *
	 *       foobar
	 *
	 * some description

will be considered as if "foobar" was part of the description.

This patch changes kernel-doc behavior. After it, foobar will
be considered as part of the parameter text. The description
will only be considered as such if it starts with:

zero spaces after asterisk:

	*foo

one space after asterisk:
	* foo

or have a explicit Description section:

	*   Description:

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/c07d2862792d75a2691d69c9eceb7b89a0164cc0.1586881715.git.mchehab+huawei@kernel.org


Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent ee2aa759

scripts/kernel-doc

+23 −12
Original line number Diff line number Diff line
@@ -335,9 +335,10 @@ use constant { 
    STATE_NAME          => 1,        # looking for function name

    STATE_BODY_MAYBE    => 2,        # body - or maybe more description

    STATE_BODY          => 3,        # the body of the comment

    STATE_PROTO         => 4, # scanning prototype

    STATE_DOCBLOCK      => 5, # documentation block

    STATE_INLINE        => 6, # gathering documentation outside main block

    STATE_BODY_WITH_BLANK_LINE => 4, # the body, which has a blank line

    STATE_PROTO         => 5,        # scanning prototype

    STATE_DOCBLOCK      => 6,        # documentation block

    STATE_INLINE        => 7,        # gathering doc outside main block

};

my $state;

my $in_doc_sect;
@@ -1957,6 +1958,12 @@ sub process_body($$) { 
	}

    }



    if ($state == STATE_BODY_WITH_BLANK_LINE && /^\s*\*\s?\S/) {

	dump_section($file, $section, $contents);

	$section = $section_default;

	$contents = "";

    }



    if (/$doc_sect/i) { # case insensitive for supported section names

	$newsection = $1;

	$newcontents = $2;
@@ -2010,18 +2017,21 @@ sub process_body($$) { 
	$state = STATE_PROTO;

	$brcount = 0;

    } elsif (/$doc_content/) {

	# miguel-style comment kludge, look for blank lines after

	# @parameter line to signify start of description

	if ($1 eq "") {

	    if ($section =~ m/^@/ || $section eq $section_context) {

	    if ($section eq $section_context) {

		dump_section($file, $section, $contents);

		$section = $section_default;

		$contents = "";

		$new_start_line = $.;

		$state = STATE_BODY;

	    } else {

		if ($section ne $section_default) {

		    $state = STATE_BODY_WITH_BLANK_LINE;

		} else {

		    $state = STATE_BODY;

		}

		$contents .= "\n";

	    }

	    $state = STATE_BODY;

	} elsif ($state == STATE_BODY_MAYBE) {

	    # Continued declaration purpose

	    chomp($declaration_purpose);
@@ -2173,7 +2183,8 @@ sub process_file($) { 
	    process_normal();

	} elsif ($state == STATE_NAME) {

	    process_name($file, $_);

	} elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE) {

	} elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE ||

		 $state == STATE_BODY_WITH_BLANK_LINE) {

	    process_body($file, $_);

	} elsif ($state == STATE_INLINE) { # scanning for inline parameters

	    process_inline($file, $_);

CRA Git | Maintained and supported by SUSTech CRA and CCSE