[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 088/113] scripts: kernel-doc: accept blank lines on parameter desc
From: |
Paolo Bonzini |
Subject: |
[PULL 088/113] scripts: kernel-doc: accept blank lines on parameter description |
Date: |
Wed, 2 Dec 2020 03:08:24 -0500 |
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
- [PULL 050/113] hw/char/serial: Clean up unnecessary code, (continued)
- [PULL 050/113] hw/char/serial: Clean up unnecessary code, Paolo Bonzini, 2020/12/02
- [PULL 064/113] vl: extract default devices to separate functions, Paolo Bonzini, 2020/12/02
- [PULL 071/113] vl: initialize displays before preconfig loop, Paolo Bonzini, 2020/12/02
- [PULL 070/113] vl: separate qemu_resolve_machine_memdev, Paolo Bonzini, 2020/12/02
- [PULL 066/113] vl: separate qemu_create_early_backends, Paolo Bonzini, 2020/12/02
- [PULL 076/113] vl: extract softmmu/datadir.c, Paolo Bonzini, 2020/12/02
- [PULL 080/113] vl: clean up -boot variables, Paolo Bonzini, 2020/12/02
- [PULL 074/113] vl: start VM via qmp_cont, Paolo Bonzini, 2020/12/02
- [PULL 084/113] kernel-doc: add support for ____cacheline_aligned_in_smp attribute, Paolo Bonzini, 2020/12/02
- [PULL 086/113] scripts: kernel-doc: proper handle @foo->bar(), Paolo Bonzini, 2020/12/02
- [PULL 088/113] scripts: kernel-doc: accept blank lines on parameter description,
Paolo Bonzini <=
- [PULL 090/113] scripts/kernel-doc: parse __ETHTOOL_DECLARE_LINK_MODE_MASK, Paolo Bonzini, 2020/12/02
- [PULL 087/113] scripts: kernel-doc: accept negation like !@var, Paolo Bonzini, 2020/12/02
- [PULL 069/113] vl: separate qemu_apply_machine_options, Paolo Bonzini, 2020/12/02
- [PULL 051/113] treewide: do not use short-form boolean options, Paolo Bonzini, 2020/12/02
- [PULL 056/113] vl: extract qemu_init_subsystems, Paolo Bonzini, 2020/12/02
- [PULL 060/113] vl: extract various command line desugaring snippets to a new function, Paolo Bonzini, 2020/12/02
- [PULL 061/113] qemu-option: restrict qemu_opts_set to merge-lists QemuOpts, Paolo Bonzini, 2020/12/02
- [PULL 067/113] vl: separate qemu_create_late_backends, Paolo Bonzini, 2020/12/02
- [PULL 072/113] vl: move -global check earlier, Paolo Bonzini, 2020/12/02
- [PULL 073/113] migration, vl: start migration via qmp_migrate_incoming, Paolo Bonzini, 2020/12/02