Re: [PATCH 9/9] docs: kdoc: some final touches for process_name()

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

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