[PULL 088/113] scripts: kernel-doc: accept blank lines on parameter description

[Paolo Bonzini]

From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

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: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: 
https://lore.kernel.org/r/c07d2862792d75a2691d69c9eceb7b89a0164cc0.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20201117165312.118257-7-pbonzini@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
 scripts/kernel-doc | 35 +++++++++++++++++++++++------------
 1 file changed, 23 insertions(+), 12 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index e4b3cd486f..95f2d7adcf 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -334,13 +334,14 @@ my $lineprefix="";
 
 # Parser states
 use constant {
-    STATE_NORMAL        => 0, # normal code
-    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_NORMAL        => 0,        # normal code
+    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_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;
@@ -1987,6 +1988,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;
@@ -2040,18 +2047,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);
@@ -2203,7 +2213,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, $_);
-- 
2.26.2