Em Fri, 6 Jun 2025 10:34:38 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> Add some comments to process_name() to cover its broad phases of operation,
> and slightly restructure the if/then/else structure to remove some early
> returns.
>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
More comments describing the parse steps are always welcomed!
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
> scripts/lib/kdoc/kdoc_parser.py | 33 ++++++++++++++++++++-------------
> 1 file changed, 20 insertions(+), 13 deletions(-)
>
> diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
> index 55f38240d4e5..9a1ce6ed8605 100644
> --- a/scripts/lib/kdoc/kdoc_parser.py
> +++ b/scripts/lib/kdoc/kdoc_parser.py
> @@ -1219,7 +1219,9 @@ class KernelDoc:
> """
> STATE_NAME: Looking for the "name - description" line
> """
> -
> + #
> + # Check for a DOC: block and handle them specially.
> + #
> if doc_block.search(line):
> self.entry.new_start_line = ln
>
> @@ -1230,9 +1232,10 @@ class KernelDoc:
>
> self.entry.identifier = self.entry.section
> self.state = state.DOCBLOCK
> - return
> -
> - if doc_decl.search(line):
> + #
> + # Otherwise we're looking for a normal kerneldoc declaration line.
> + #
> + elif doc_decl.search(line):
> self.entry.identifier = doc_decl.group(1)
>
> # Test for data declaration
> @@ -1253,15 +1256,19 @@ class KernelDoc:
> f"This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n{line}")
> self.state = state.NORMAL
> return
> -
> - self.entry.identifier = self.entry.identifier.strip(" ")
> -
> + #
> + # OK, set up for a new kerneldoc entry.
> + #
> self.state = state.BODY
> -
> + self.entry.identifier = self.entry.identifier.strip(" ")
> # if there's no @param blocks need to set up default section here
> self.entry.section = SECTION_DEFAULT
> self.entry.new_start_line = ln + 1
> -
> + #
> + # Find the description portion, which *should* be there but
> + # isn't always.
> + # (We should be able to capture this from the previous parsing - someday)
> + #
> r = KernRe("[-:](.*)")
> if r.search(line):
> self.entry.declaration_purpose = trim_whitespace(r.group(1))
> @@ -1282,11 +1289,11 @@ class KernelDoc:
> self.emit_msg(ln,
> f"Scanning doc for {self.entry.decl_type} {self.entry.identifier}",
> warning=False)
> -
> - return
> -
> + #
> # Failed to find an identifier. Emit a warning
> - self.emit_msg(ln, f"Cannot find identifier on line:\n{line}")
> + #
> + else:
> + self.emit_msg(ln, f"Cannot find identifier on line:\n{line}")
>
> def process_body(self, ln, line):
> """
Thanks,
Mauro