Re: [PATCH 01/12] docs: kdoc: consolidate the stripping of private struct/union members

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

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

> There were two locations duplicating the logic of stripping private members
> and associated comments; coalesce them into one, and add some comments
> describing what's going on.
> 
> Output change: we now no longer add extraneous white space around macro
> definitions.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>

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

> ---
>  scripts/lib/kdoc/kdoc_parser.py | 40 ++++++++++++++++++---------------
>  1 file changed, 22 insertions(+), 18 deletions(-)
> 
> diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
> index c3fe4bd5eab4..93fcd8807aa8 100644
> --- a/scripts/lib/kdoc/kdoc_parser.py
> +++ b/scripts/lib/kdoc/kdoc_parser.py
> @@ -81,6 +81,21 @@ multi_space = KernRe(r'\s\s+')
>  def trim_whitespace(s):
>      return multi_space.sub(' ', s.strip())
>  
> +#
> +# Remove struct/enum members that have been marked "private".
> +#
> +def trim_private_members(text):
> +    #
> +    # First look for a "public:" block that ends a private region, then
> +    # handle the "private until the end" case.
> +    #
> +    text = KernRe(r'/\*\s*private:.*?/\*\s*public:.*?\*/', flags=re.S).sub('', text)
> +    text = KernRe(r'/\*\s*private:.*', flags=re.S).sub('', text)
> +    #
> +    # We needed the comments to do the above, but now we can take them out.
> +    #
> +    return KernRe(r'\s*/\*.*?\*/\s*', flags=re.S).sub('', text).strip()
> +
>  class state:
>      """
>      State machine enums
> @@ -568,12 +583,6 @@ class KernelDoc:
>          args_pattern = r'([^,)]+)'
>  
>          sub_prefixes = [
> -            (KernRe(r'\/\*\s*private:.*?\/\*\s*public:.*?\*\/', re.S | re.I), ''),
> -            (KernRe(r'\/\*\s*private:.*', re.S | re.I), ''),
> -
> -            # Strip comments
> -            (KernRe(r'\/\*.*?\*\/', re.S), ''),
> -
>              # Strip attributes
>              (attribute, ' '),
>              (KernRe(r'\s*__aligned\s*\([^;]*\)', re.S), ' '),
> @@ -648,6 +657,7 @@ class KernelDoc:
>              (re.compile(r'\bSTRUCT_GROUP\('), r'\1'),
>          ]
>  
> +        members = trim_private_members(members)
>          for search, sub in sub_prefixes:
>              members = search.sub(sub, members)
>  
> @@ -797,24 +807,18 @@ class KernelDoc:
>          """
>          Stores an enum inside self.entries array.
>          """
> -
> -        # Ignore members marked private
> -        proto = KernRe(r'\/\*\s*private:.*?\/\*\s*public:.*?\*\/', flags=re.S).sub('', proto)
> -        proto = KernRe(r'\/\*\s*private:.*}', flags=re.S).sub('}', proto)
> -
> -        # Strip comments
> -        proto = KernRe(r'\/\*.*?\*\/', flags=re.S).sub('', proto)
> -
> -        # Strip #define macros inside enums
> +        #
> +        # Strip preprocessor directives.  Note that this depends on the
> +        # trailing semicolon we added in process_proto_type().
> +        #
>          proto = KernRe(r'#\s*((define|ifdef|if)\s+|endif)[^;]*;', flags=re.S).sub('', proto)
> -
>          #
>          # Parse out the name and members of the enum.  Typedef form first.
>          #
>          r = KernRe(r'typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;')
>          if r.search(proto):
>              declaration_name = r.group(2)
> -            members = r.group(1).rstrip()
> +            members = trim_private_members(r.group(1))
>          #
>          # Failing that, look for a straight enum
>          #
> @@ -822,7 +826,7 @@ class KernelDoc:
>              r = KernRe(r'enum\s+(\w*)\s*\{(.*)\}')
>              if r.match(proto):
>                  declaration_name = r.group(1)
> -                members = r.group(2).rstrip()
> +                members = trim_private_members(r.group(2))
>          #
>          # OK, this isn't going to work.
>          #



Thanks,
Mauro