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@lwn.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
         tuples = struct_members.findall(members)
         while tuples:
             for t in tuples:
-- 
2.50.1

Em Thu, 31 Jul 2025 18:13:23 -0600
Jonathan Corbet <corbet@lwn.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@lwn.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@kernel.org>

Thanks,
Mauro