[PATCH v2 18/28] docs: xforms_lists: better evaluate struct_group macros

Mauro Carvalho Chehab
2026-03-12T14:55:00Z

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 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@kernel.org>
---
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