linux-kernel - Re: [PATCH 09/12] docs: kdoc: Some rewrite_struct

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20250801075011.04645db6@foz.lan>
Date: Fri, 1 Aug 2025 07:50:11 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Jonathan Corbet <corbet@....net>
Cc: linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org, Akira Yokosawa
 <akiyks@...il.com>
Subject: Re: [PATCH 09/12] docs: kdoc: Some rewrite_struct_members()
 commenting

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

> Add comments to rewrite_struct_members() describing what it is actually
> doing, and reformat/comment the main struct_members regex so that it is
> (more) comprehensible to humans.
> 
> Signed-off-by: Jonathan Corbet <corbet@....net>
> ---
>  scripts/lib/kdoc/kdoc_parser.py | 32 +++++++++++++++++++-------------
>  1 file changed, 19 insertions(+), 13 deletions(-)
> 
> diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
> index b751fa8edde7..20e0a2abe13b 100644
> --- a/scripts/lib/kdoc/kdoc_parser.py
> +++ b/scripts/lib/kdoc/kdoc_parser.py
> @@ -647,22 +647,28 @@ class KernelDoc:
>                  return (r.group(1), r.group(3), r.group(2))
>          return None
>  
> +    #
> +    # Rewrite the members of a structure or union for easier formatting later on.
> +    # Among other things, this function will turn a member like:
> +    #
> +    #  struct { inner_members; } foo;
> +    #
> +    # into:
> +    #
> +    #  struct foo; inner_members;
> +    #
>      def rewrite_struct_members(self, members):
> -        # Split nested struct/union elements
> -        #
> -        # This loop was simpler at the original kernel-doc perl version, as
> -        #   while ($members =~ m/$struct_members/) { ... }
> -        # reads 'members' string on each interaction.
>          #
> -        # Python behavior is different: it parses 'members' only once,
> -        # creating a list of tuples from the first interaction.
> +        # Process struct/union members from the most deeply nested outward.  The
> +        # trick is in the ^{ below - it prevents a match of an outer struct/union
> +        # until the inner one has been munged (removing the "{" in the process).
>          #
> -        # On other words, this won't get nested structs.
> -        #
> -        # So, we need to have an extra loop on Python to override such
> -        # re limitation.
> -
> -        struct_members = KernRe(r'(struct|union)([^{};]+)(\{)([^{}]*)(\})([^{};]*)(;)')
> +        struct_members = KernRe(r'(struct|union)' # 0: declaration type
> +                                r'([^{};]+)' 	  # 1: possible name
> +                                r'(\{)'
> +                                r'([^{}]*)'       # 3: Contents of declaration
> +                                r'(\})'
> +                                r'([^{};]*)(;)')  # 5: Remaining stuff after declaration

I liked breaking it like these, but I do miss backslashes before some
'{' and '}' to make this actually more readable on my eyes.

Re-adding that, you can add:
	Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>

Thanks,
Mauro