From: Paolo Bonzini <pbonzini@redhat.com>
To: qemu-devel@nongnu.org
Subject: [PATCH 06/29] scripts: kernel-doc: accept blank lines on parameter description
Date: Tue, 17 Nov 2020 17:52:49 +0100 [thread overview]
Message-ID: <20201117165312.118257-7-pbonzini@redhat.com> (raw)
In-Reply-To: <20201117165312.118257-1-pbonzini@redhat.com>
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>
---
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.28.0
next prev parent reply other threads:[~2020-11-17 16:54 UTC|newest]
Thread overview: 32+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-11-17 16:52 [RFC PATCH 00/29] kernel-doc: update from Linux 5.10 Paolo Bonzini
2020-11-17 16:52 ` [PATCH 01/29] kernel-doc: fix processing nested structs with attributes Paolo Bonzini
2020-11-17 16:52 ` [PATCH 02/29] kernel-doc: add support for ____cacheline_aligned_in_smp attribute Paolo Bonzini
2020-11-17 16:52 ` [PATCH 03/29] scripts/kernel-doc: Add support for named variable macro arguments Paolo Bonzini
2020-11-17 16:52 ` [PATCH 04/29] scripts: kernel-doc: proper handle @foo->bar() Paolo Bonzini
2020-11-17 16:52 ` [PATCH 05/29] scripts: kernel-doc: accept negation like !@var Paolo Bonzini
2020-11-17 16:52 ` Paolo Bonzini [this message]
2020-11-17 16:52 ` [PATCH 07/29] Replace HTTP links with HTTPS ones: documentation Paolo Bonzini
2020-11-17 16:52 ` [PATCH 08/29] scripts/kernel-doc: parse __ETHTOOL_DECLARE_LINK_MODE_MASK Paolo Bonzini
2020-11-17 16:52 ` [PATCH 09/29] scripts/kernel-doc: handle function pointer prototypes Paolo Bonzini
2020-11-17 16:52 ` [PATCH 10/29] scripts/kernel-doc: optionally treat warnings as errors Paolo Bonzini
2020-11-17 16:52 ` [PATCH 11/29] kernel-doc: include line numbers for function prototypes Paolo Bonzini
2020-11-17 16:52 ` [PATCH 12/29] kernel-doc: add support for ____cacheline_aligned attribute Paolo Bonzini
2020-11-17 16:52 ` [PATCH 13/29] scripts: kernel-doc: add support for typedef enum Paolo Bonzini
2020-11-17 16:52 ` [PATCH 14/29] Revert "scripts/kerneldoc: For Sphinx 3 use c:macro for macros with arguments" Paolo Bonzini
2020-11-17 16:52 ` [PATCH 15/29] Revert "kernel-doc: Use c:struct for Sphinx 3.0 and later" Paolo Bonzini
2020-11-17 16:52 ` [PATCH 16/29] scripts: kernel-doc: make it more compatible with Sphinx 3.x Paolo Bonzini
2020-11-17 16:53 ` [PATCH 17/29] scripts: kernel-doc: use a less pedantic markup for funcs on " Paolo Bonzini
2020-11-17 16:53 ` [PATCH 18/29] scripts: kernel-doc: fix troubles with line counts Paolo Bonzini
2020-11-17 16:53 ` [PATCH 19/29] scripts: kernel-doc: reimplement -nofunction argument Paolo Bonzini
2020-11-17 16:53 ` [PATCH 20/29] scripts: kernel-doc: fix typedef identification Paolo Bonzini
2020-11-17 16:53 ` [PATCH 21/29] scripts: kernel-doc: don't mangle with parameter list Paolo Bonzini
2020-11-17 16:53 ` [PATCH 22/29] scripts: kernel-doc: allow passing desired Sphinx C domain dialect Paolo Bonzini
2020-11-17 16:53 ` [PATCH 23/29] scripts: kernel-doc: fix line number handling Paolo Bonzini
2020-11-17 16:53 ` [PATCH 24/29] scripts: kernel-doc: try to use c:function if possible Paolo Bonzini
2020-11-17 16:53 ` [PATCH 25/29] Revert "kernel-doc: Handle function typedefs without asterisks" Paolo Bonzini
2020-11-17 16:53 ` [PATCH 26/29] Revert "kernel-doc: Handle function typedefs that return pointers" Paolo Bonzini
2020-11-17 16:53 ` [PATCH 27/29] scripts: kernel-doc: fix typedef parsing Paolo Bonzini
2020-11-17 16:53 ` [PATCH 28/29] scripts: kernel-doc: split typedef complex regex Paolo Bonzini
2020-11-17 16:53 ` [PATCH 29/29] scripts: kernel-doc: use :c:union when needed Paolo Bonzini
2020-11-30 11:28 ` [RFC PATCH 00/29] kernel-doc: update from Linux 5.10 Peter Maydell
2020-11-30 11:59 ` Paolo Bonzini
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20201117165312.118257-7-pbonzini@redhat.com \
--to=pbonzini@redhat.com \
--cc=qemu-devel@nongnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.