From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Linux Doc Mailing List <linux-doc@vger.kernel.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
linux-kernel@vger.kernel.org, Jonathan Corbet <corbet@lwn.net>
Subject: [PATCH v2 03/33] scripts: kernel-doc: accept blank lines on parameter description
Date: Tue, 14 Apr 2020 18:48:29 +0200 [thread overview]
Message-ID: <c07d2862792d75a2691d69c9eceb7b89a0164cc0.1586881715.git.mchehab+huawei@kernel.org> (raw)
In-Reply-To: <cover.1586881715.git.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>
---
scripts/kernel-doc | 35 +++++++++++++++++++++++------------
1 file changed, 23 insertions(+), 12 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index b019d8db6502..41ed4202f4ad 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -331,13 +331,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;
@@ -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, $_);
--
2.25.2
next prev parent reply other threads:[~2020-04-14 16:49 UTC|newest]
Thread overview: 46+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-04-14 16:48 [PATCH v2 00/33] Documentation fixes for Kernel 5.8 Mauro Carvalho Chehab
2020-04-14 16:48 ` [PATCH v2 01/33] scripts: kernel-doc: proper handle @foo->bar() Mauro Carvalho Chehab
2020-04-14 16:48 ` [PATCH v2 02/33] scripts: kernel-doc: accept negation like !@var Mauro Carvalho Chehab
2020-04-14 16:48 ` Mauro Carvalho Chehab [this message]
2020-04-14 16:48 ` [PATCH v2 04/33] docs: update recommended Sphinx version to 2.4.4 Mauro Carvalho Chehab
2020-04-20 21:27 ` Jonathan Corbet
2020-04-20 22:12 ` Mauro Carvalho Chehab
2020-04-14 16:48 ` [PATCH v2 05/33] docs: LaTeX/PDF: drop list of documents Mauro Carvalho Chehab
2020-04-14 16:48 ` [PATCH v2 06/33] MAINTAINERS: dt: update display/allwinner file entry Mauro Carvalho Chehab
2020-04-16 21:14 ` Rob Herring
2020-04-14 16:48 ` [PATCH v2 07/33] MAINTAINERS: dt: fix pointers for ARM Integrator, Versatile and RealView Mauro Carvalho Chehab
2020-04-14 16:48 ` [PATCH v2 08/33] docs: dt: fix broken reference to phy-cadence-torrent.yaml Mauro Carvalho Chehab
2020-04-14 21:01 ` Rob Herring
2020-04-14 16:48 ` [PATCH v2 10/33] docs: fix broken references for ReST files that moved around Mauro Carvalho Chehab
2020-04-16 8:31 ` Corentin Labbe
2020-04-14 16:48 ` [PATCH v2 11/33] docs: filesystems: fix renamed references Mauro Carvalho Chehab
2020-04-14 16:48 ` [PATCH v2 12/33] docs: amu: supress some Sphinx warnings Mauro Carvalho Chehab
2020-04-14 16:48 ` [PATCH v2 13/33] docs: arm64: booting.rst: get rid of some warnings Mauro Carvalho Chehab
2020-04-14 16:48 ` [PATCH v2 14/33] docs: pci: boot-interrupts.rst: improve html output Mauro Carvalho Chehab
2020-04-14 16:48 ` [PATCH v2 15/33] docs: ras: get rid of some warnings Mauro Carvalho Chehab
2020-04-14 16:48 ` [PATCH v2 16/33] docs: ras: don't need to repeat twice the same thing Mauro Carvalho Chehab
2020-04-14 16:48 ` [PATCH v2 17/33] docs: infiniband: verbs.c: fix some documentation warnings Mauro Carvalho Chehab
2020-04-14 19:33 ` Jason Gunthorpe
2020-04-14 16:48 ` [PATCH v2 18/33] docs: spi: spi.h: fix a doc building warning Mauro Carvalho Chehab
2020-04-14 16:54 ` Mark Brown
2020-04-14 16:48 ` [PATCH v2 19/33] docs: drivers: fix some warnings at base/platform.c when building docs Mauro Carvalho Chehab
2020-04-14 16:48 ` [PATCH v2 20/33] docs: mm: userfaultfd.rst: use ``foo`` for literals Mauro Carvalho Chehab
2020-04-14 16:48 ` [PATCH v2 21/33] docs: mm: userfaultfd.rst: use a cross-reference for a section Mauro Carvalho Chehab
2020-04-14 16:48 ` [PATCH v2 22/33] docs: vm: index.rst: add an orphan doc to the building system Mauro Carvalho Chehab
2020-04-14 16:48 ` [PATCH v2 23/33] docs: dt: qcom,dwc3.txt: fix cross-reference for a converted file Mauro Carvalho Chehab
2020-04-14 21:01 ` Rob Herring
2020-04-14 16:48 ` [PATCH v2 24/33] docs: dt: fix a broken reference for a file converted to json Mauro Carvalho Chehab
2020-04-14 21:02 ` Rob Herring
2020-04-14 16:48 ` [PATCH v2 25/33] docs: powerpc: cxl.rst: mark two section titles as such Mauro Carvalho Chehab
2020-04-15 0:16 ` Andrew Donnellan
2020-04-14 16:48 ` [PATCH v2 26/33] docs: i2c: rename i2c.svg to i2c_bus.svg Mauro Carvalho Chehab
2020-04-14 16:48 ` [PATCH v2 27/33] docs: Makefile: place final pdf docs on a separate dir Mauro Carvalho Chehab
2020-04-14 16:48 ` [PATCH v2 28/33] docs: dt: rockchip,dwc3.txt: fix a pointer to a renamed file Mauro Carvalho Chehab
2020-04-14 21:02 ` Rob Herring
2020-04-14 16:48 ` [PATCH v2 29/33] ata: libata-core: fix a doc warning Mauro Carvalho Chehab
2020-04-14 16:48 ` [PATCH v2 30/33] firewire: firewire-cdev.hL get rid of a docs warning Mauro Carvalho Chehab
2020-04-14 16:48 ` [PATCH v2 31/33] fs: inode.c: get rid of docs warnings Mauro Carvalho Chehab
2020-04-14 16:48 ` [PATCH v2 32/33] futex: get rid of a kernel-docs build warning Mauro Carvalho Chehab
2020-04-14 16:48 ` [PATCH v2 33/33] lib: bitmap.c: get rid of some doc warnings Mauro Carvalho Chehab
2020-04-24 17:30 ` Peter Lister
2020-04-20 21:43 ` [PATCH v2 00/33] Documentation fixes for Kernel 5.8 Jonathan Corbet
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=c07d2862792d75a2691d69c9eceb7b89a0164cc0.1586881715.git.mchehab+huawei@kernel.org \
--to=mchehab+huawei@kernel.org \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.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 a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).