The state known as BODY_WITH_BLANK_LINE really, in a convoluted way,
indicates a "special section" that is terminated by a blank line or the
beginning of a new section. That is either "@param: desc" sections, or the
weird "context" section that plays by the same rules.
Rename the state to SPECIAL_SECTION and split its processing into a
separate function; no real changes to the logic yet.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
scripts/lib/kdoc/kdoc_parser.py | 24 ++++++++++++------------
1 file changed, 12 insertions(+), 12 deletions(-)
diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
index f1491f8c88e7..185ffe4e1469 100644
--- a/scripts/lib/kdoc/kdoc_parser.py
+++ b/scripts/lib/kdoc/kdoc_parser.py
@@ -88,7 +88,7 @@ class state:
NAME = 1 # looking for function name
DECLARATION = 2 # We have seen a declaration which might not be done
BODY = 3 # the body of the comment
- BODY_WITH_BLANK_LINE = 4 # the body which has a blank line
+ SPECIAL_SECTION = 4 # doc section ending with a blank line
PROTO = 5 # scanning prototype
DOCBLOCK = 6 # documentation block
INLINE = 7 # gathering doc outside main block
@@ -98,7 +98,7 @@ class state:
"NAME",
"DECLARATION",
"BODY",
- "BODY_WITH_BLANK_LINE",
+ "SPECIAL_SECTION",
"PROTO",
"DOCBLOCK",
"INLINE",
@@ -1383,18 +1383,18 @@ class KernelDoc:
self.emit_msg(ln, f"bad line: {line}")
+ def process_special(self, ln, line):
+ """
+ STATE_SPECIAL_SECTION: a section ending with a blank line
+ """
+ if KernRe(r"\s*\*\s*\S").match(line):
+ self.entry.begin_section(ln, dump = True)
+ self.process_body(ln, line)
+
def process_body(self, ln, line):
"""
STATE_BODY: the bulk of a kerneldoc comment.
"""
-
- if self.state == state.BODY_WITH_BLANK_LINE:
- r = KernRe(r"\s*\*\s*\S")
- if r.match(line):
- self.dump_section()
- self.entry.begin_section(ln)
- self.entry.contents = ""
-
if doc_sect.search(line):
self.entry.in_doc_sect = True
newsection = doc_sect.group(1)
@@ -1452,7 +1452,7 @@ class KernelDoc:
self.state = state.BODY
else:
if self.entry.section != SECTION_DEFAULT:
- self.state = state.BODY_WITH_BLANK_LINE
+ self.state = state.SPECIAL_SECTION
else:
self.state = state.BODY
@@ -1751,7 +1751,7 @@ class KernelDoc:
state.NAME: process_name,
state.BODY: process_body,
state.DECLARATION: process_decl,
- state.BODY_WITH_BLANK_LINE: process_body,
+ state.SPECIAL_SECTION: process_special,
state.INLINE: process_inline,
state.PROTO: process_proto,
state.DOCBLOCK: process_docblock,
--
2.49.0Em Sat, 21 Jun 2025 14:35:07 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> The state known as BODY_WITH_BLANK_LINE really, in a convoluted way,
> indicates a "special section" that is terminated by a blank line or the
> beginning of a new section. That is either "@param: desc" sections, or the
> weird "context" section that plays by the same rules.
>
> Rename the state to SPECIAL_SECTION and split its processing into a
> separate function; no real changes to the logic yet.
LGTM.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
> scripts/lib/kdoc/kdoc_parser.py | 24 ++++++++++++------------
> 1 file changed, 12 insertions(+), 12 deletions(-)
>
> diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
> index f1491f8c88e7..185ffe4e1469 100644
> --- a/scripts/lib/kdoc/kdoc_parser.py
> +++ b/scripts/lib/kdoc/kdoc_parser.py
> @@ -88,7 +88,7 @@ class state:
> NAME = 1 # looking for function name
> DECLARATION = 2 # We have seen a declaration which might not be done
> BODY = 3 # the body of the comment
> - BODY_WITH_BLANK_LINE = 4 # the body which has a blank line
> + SPECIAL_SECTION = 4 # doc section ending with a blank line
> PROTO = 5 # scanning prototype
> DOCBLOCK = 6 # documentation block
> INLINE = 7 # gathering doc outside main block
> @@ -98,7 +98,7 @@ class state:
> "NAME",
> "DECLARATION",
> "BODY",
> - "BODY_WITH_BLANK_LINE",
> + "SPECIAL_SECTION",
> "PROTO",
> "DOCBLOCK",
> "INLINE",
> @@ -1383,18 +1383,18 @@ class KernelDoc:
> self.emit_msg(ln, f"bad line: {line}")
>
>
> + def process_special(self, ln, line):
> + """
> + STATE_SPECIAL_SECTION: a section ending with a blank line
> + """
> + if KernRe(r"\s*\*\s*\S").match(line):
> + self.entry.begin_section(ln, dump = True)
> + self.process_body(ln, line)
> +
> def process_body(self, ln, line):
> """
> STATE_BODY: the bulk of a kerneldoc comment.
> """
> -
> - if self.state == state.BODY_WITH_BLANK_LINE:
> - r = KernRe(r"\s*\*\s*\S")
> - if r.match(line):
> - self.dump_section()
> - self.entry.begin_section(ln)
> - self.entry.contents = ""
> -
> if doc_sect.search(line):
> self.entry.in_doc_sect = True
> newsection = doc_sect.group(1)
> @@ -1452,7 +1452,7 @@ class KernelDoc:
> self.state = state.BODY
> else:
> if self.entry.section != SECTION_DEFAULT:
> - self.state = state.BODY_WITH_BLANK_LINE
> + self.state = state.SPECIAL_SECTION
> else:
> self.state = state.BODY
>
> @@ -1751,7 +1751,7 @@ class KernelDoc:
> state.NAME: process_name,
> state.BODY: process_body,
> state.DECLARATION: process_decl,
> - state.BODY_WITH_BLANK_LINE: process_body,
> + state.SPECIAL_SECTION: process_special,
> state.INLINE: process_inline,
> state.PROTO: process_proto,
> state.DOCBLOCK: process_docblock,
Thanks,
Mauro
© 2016 - 2026 Red Hat, Inc.