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 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.

Mauro Carvalho Chehab committed 7 months ago

Commit 2f07ddb1 parent f63e6161 file · +10 −4Browse files

Showing the changes to tools/lib/python (1 of 1 file). Show all

Unified · Split

tools/lib/python/kdoc/xforms_lists.py+10−4

@@ -61,10 +61,16 @@ class CTransforms: · 60 unmodified lines
61	61	(CMatch(r"__acquires_shared"), ""),
62	62	(CMatch(r"__releases_shared"), ""),
63	63
64		− (CMatch('struct_group'), r'\2'),
65		− (CMatch('struct_group_attr'), r'\3'),
66		− (CMatch('struct_group_tagged'), r'struct \1 \2; \3'),
67		− (CMatch('__struct_group'), r'\4'),
	64	+ #
	65	+ # Macro __struct_group() creates an union with an anonymous
	66	+ # and a non-anonymous struct, depending on the parameters. We only
	67	+ # need one of those at kernel-doc, as we won't be documenting the same
	68	+ # members twice.
	69	+ #
	70	+ (CMatch('struct_group'), r'struct { \2+ };'),
	71	+ (CMatch('struct_group_attr'), r'struct { \3+ };'),
	72	+ (CMatch('struct_group_tagged'), r'struct { \3+ };'),
	73	+ (CMatch('__struct_group'), r'struct { \4+ };'),
68	74
69	75	]
70	76