RE: [PATCH v3 17/22] docs: xforms_lists: better evaluate struct_group macros

[Loktionov, Aleksandr]

> -----Original Message-----
> From: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
> Sent: Tuesday, March 17, 2026 7:10 PM
> To: Jonathan Corbet <corbet@xxxxxxx>; Linux Doc Mailing List <linux-
> doc@xxxxxxxxxxxxxxx>
> Cc: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>; linux-
> hardening@xxxxxxxxxxxxxxx; linux-kernel@xxxxxxxxxxxxxxx; Loktionov,
> Aleksandr <aleksandr.loktionov@xxxxxxxxx>; Randy Dunlap
> <rdunlap@xxxxxxxxxxxxx>
> Subject: [PATCH v3 17/22] docs: xforms_lists: better evaluate
> struct_group macros
> 
> The previous approach were to unwind nested structs/unions.
> 
> Now that we have a logic that can handle it well, use it to ensure
> that struct_group macros will properly reflect the actual struct.
> 
> Note that the replacemend logic still simplifies the code a little
replacemend -> replacement

Otherwise, fine
Reviewed-by: Aleksandr Loktionov <aleksandr.loktionov@xxxxxxxxx>

> bit, as the basic build block for struct group is:
> 
> 	union { \
> 		struct { MEMBERS } ATTRS; \
> 		struct __struct_group_tag(TAG) { MEMBERS } ATTRS NAME; \
> 	} ATTRS
> 
> There:
> 
> - ATTRS is meant to add extra macro attributes like __packed
>   which we already discard, as they aren't relevant to
>   document struct members;
> 
> - TAG is used only when built with __cplusplus.
> 
> So, instead, convert them into just:
> 
>     struct { MEMBERS };
> 
> Please notice that here, we're using the greedy version of the
> backrefs, as MEMBERS is actually MEMBERS... on all such macros.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
> ---
>  tools/lib/python/kdoc/xforms_lists.py | 14 ++++++++++----
>  1 file changed, 10 insertions(+), 4 deletions(-)
> 
> diff --git a/tools/lib/python/kdoc/xforms_lists.py
> b/tools/lib/python/kdoc/xforms_lists.py
> index 98632c50a146..2056572852fd 100644
> --- a/tools/lib/python/kdoc/xforms_lists.py
> +++ b/tools/lib/python/kdoc/xforms_lists.py
> @@ -61,10 +61,16 @@ class CTransforms:
>          (CMatch(r"__acquires_shared"), ""),
>          (CMatch(r"__releases_shared"), ""),
> 
> -        (CMatch('struct_group'), r'\2'),
> -        (CMatch('struct_group_attr'), r'\3'),
> -        (CMatch('struct_group_tagged'), r'struct \1 \2; \3'),
> -        (CMatch('__struct_group'), r'\4'),
> +        #
> +        # Macro __struct_group() creates an union with an anonymous
> +        # and a non-anonymous struct, depending on the parameters. We
> only
> +        # need one of those at kernel-doc, as we won't be documenting
> the same
> +        # members twice.
> +        #
> +        (CMatch('struct_group'), r'struct { \2+ };'),
> +        (CMatch('struct_group_attr'), r'struct { \3+ };'),
> +        (CMatch('struct_group_tagged'), r'struct { \3+ };'),
> +        (CMatch('__struct_group'), r'struct { \4+ };'),
> 
>      ]
> 
> --
> 2.52.0