> -----Original Message----- > From: Mauro Carvalho Chehab <[email protected]> > Sent: Tuesday, March 17, 2026 7:10 PM > To: Jonathan Corbet <[email protected]>; Linux Doc Mailing List <linux- > [email protected]> > Cc: Mauro Carvalho Chehab <[email protected]>; linux- > [email protected]; [email protected]; Loktionov, > Aleksandr <[email protected]>; Randy Dunlap > <[email protected]> > 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 <[email protected]> > 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 <[email protected]> > --- > 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
