Re: [PATCH 05/12] docs: kdoc: split top-level prototype parsing out of dump_struct()

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

Em Thu, 31 Jul 2025 18:13:19 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Move the initial split of the prototype into its own function in the
> ongoing effort to cut dump_struct() down to size.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
>  scripts/lib/kdoc/kdoc_parser.py | 44 +++++++++++++++------------------
>  1 file changed, 20 insertions(+), 24 deletions(-)
> 
> diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
> index 5e375318df9c..2bb0da22048f 100644
> --- a/scripts/lib/kdoc/kdoc_parser.py
> +++ b/scripts/lib/kdoc/kdoc_parser.py
> @@ -624,13 +624,11 @@ class KernelDoc:
>              self.emit_msg(ln,
>                            f"No description found for return value of '{declaration_name}'")
>  
> -    def dump_struct(self, ln, proto):
> -        """
> -        Store an entry for an struct or union
> -        """
> -
> +    #
> +    # Split apart a structure prototype; returns (struct|union, name, members) or None
> +    #
> +    def split_struct_proto(self, proto):
>          type_pattern = r'(struct|union)'
> -
>          qualifiers = [
>              "__attribute__",
>              "__packed",
> @@ -638,36 +636,34 @@ class KernelDoc:
>              "____cacheline_aligned_in_smp",
>              "____cacheline_aligned",
>          ]
> -
>          definition_body = r'\{(.*)\}\s*' + "(?:" + '|'.join(qualifiers) + ")?"
>  
> -        # Extract struct/union definition
> -        members = None
> -        declaration_name = None
> -        decl_type = None
> -
>          r = KernRe(type_pattern + r'\s+(\w+)\s*' + definition_body)
>          if r.search(proto):
> -            decl_type = r.group(1)
> -            declaration_name = r.group(2)
> -            members = r.group(3)
> +            return (r.group(1), r.group(2), r.group(3))
>          else:
>              r = KernRe(r'typedef\s+' + type_pattern + r'\s*' + definition_body + r'\s*(\w+)\s*;')
> -
>              if r.search(proto):
> -                decl_type = r.group(1)
> -                declaration_name = r.group(3)
> -                members = r.group(2)
> +                return (r.group(1), r.group(3), r.group(2))
> +        return None
>  
> -        if not members:
> +    def dump_struct(self, ln, proto):
> +        """
> +        Store an entry for an struct or union
> +        """
> +        #
> +        # Do the basic parse to get the pieces of the declaration.
> +        #
> +        struct_parts = self.split_struct_proto(proto)
> +        if not struct_parts:
>              self.emit_msg(ln, f"{proto} error: Cannot parse struct or union!")
>              return
> +        decl_type, declaration_name, members = struct_parts
>  
>          if self.entry.identifier != declaration_name:
> -            self.emit_msg(ln,
> -                          f"expecting prototype for {decl_type} {self.entry.identifier}. Prototype was for {decl_type} {declaration_name} instead\n")
> +            self.emit_msg(ln, f"expecting prototype for {decl_type} {self.entry.identifier}. "
> +                          f"Prototype was for {decl_type} {declaration_name} instead\n")
>              return
> -
>          #
>          # Go through the list of members applying all of our transformations.
>          #
> @@ -696,7 +692,7 @@ class KernelDoc:
>          # So, we need to have an extra loop on Python to override such
>          # re limitation.
>  
> -        struct_members = KernRe(type_pattern + r'([^{};]+)(\{)([^{}]*)(\})([^{};]*)(;)')
> +        struct_members = KernRe(r'(struct|union)([^{};]+)(\{)([^{}]*)(\})([^{};]*)(;)')

I would prefer keeping type_pattern here. 

With that:

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>


>          while True:
>              tuples = struct_members.findall(members)
>              if not tuples:



Thanks,
Mauro