[PATCH] docs: kdoc: fix struct_group_tagged() parsing regression
From: Omokefe Emmanuel Onanaroghene <hidden>
Date: 2026-09-14 15:57:10
Also in:
intel-wired-lan, linux-doc, lkml
Subsystem:
documentation, documentation scripts, the rest · Maintainers:
Jonathan Corbet, Mauro Carvalho Chehab, Linus Torvalds
kernel-doc reports struct_group_tagged() members as excess because the macro transformation rewrites it to an anonymous struct and drops their member names. Keep the tag and member name when transforming struct_group_tagged(). The nested members are then recorded as names such as fast.order; accept the existing unqualified @order documentation tag during validation. Add a regression test based on struct page_pool_params. Reported-by: Randy Dunlap <rdunlap@infradead.org> Link: https://lore.kernel.org/all/0cf8ea5f-418f-45f0-907c-3d1ed4f03e9f@infradead.org/ (local) Fixes: 2f07ddbd5793 ("docs: xforms_lists: better evaluate struct_group macros") Signed-off-by: Omokefe Emmanuel Onanaroghene <redacted> --- tools/lib/python/kdoc/kdoc_parser.py | 4 ++- tools/lib/python/kdoc/xforms_lists.py | 2 +- tools/unittests/test_kdoc_parser.py | 37 +++++++++++++++++++++++++++ 3 files changed, 41 insertions(+), 2 deletions(-)
diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
index d9ad1ddc87dd..ced09504f3d7 100644
--- a/tools/lib/python/kdoc/kdoc_parser.py
+++ b/tools/lib/python/kdoc/kdoc_parser.py@@ -635,7 +635,9 @@ class KernelDoc: continue if param_name.startswith("{unnamed_"): continue - if param_name in self.entry.parameterlist: + if param_name in self.entry.parameterlist or \ + any(actual.endswith('.' + param_name) + for actual in self.entry.parameterlist): continue hint = self.get_suggestions_hint(param_name, self.entry.parameterlist)
diff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/xforms_lists.py
index e3dda2fe8a53..9e8b3a6b1da1 100644
--- a/tools/lib/python/kdoc/xforms_lists.py
+++ b/tools/lib/python/kdoc/xforms_lists.py@@ -60,7 +60,7 @@ class CTransforms: # (CMatch("struct_group"), r"struct { \2+ };"), (CMatch("struct_group_attr"), r"struct { \3+ };"), - (CMatch("struct_group_tagged"), r"struct { \3+ };"), + (CMatch("struct_group_tagged"), r"struct \1 { \3+ } \2;"), (CMatch("__struct_group"), r"struct { \4+ };"), ]
diff --git a/tools/unittests/test_kdoc_parser.py b/tools/unittests/test_kdoc_parser.py
index c4a76ed13dbc..1a8287e99f2e 100755
--- a/tools/unittests/test_kdoc_parser.py
+++ b/tools/unittests/test_kdoc_parser.py@@ -418,6 +418,43 @@ class TestSelfValidate(GenerateKdocItem): """ self.run_test(self.SOURCE, [self.DEFAULT.copy()], self.EXPORTS) + +class TestStructGroupTagged(GenerateKdocItem): + def test_nested_struct_group_tagged_members(self): + source = """ + /** + * struct page_pool_params - page pool parameters + * @fast: Fast path parameters. + * @order: Order of pages. + * @pool_size: Number of pages. + * @slow: Slow path parameters. + * @netdev: Net device pointer. + * @queue_idx: Queue index. + * @flags: Flags. + */ + struct page_pool_params { + struct_group_tagged(page_pool_params_fast, fast, + unsigned int order; + unsigned int pool_size; + ); + struct_group_tagged(page_pool_params_slow, slow, + struct net_device *netdev; + unsigned int queue_idx; + unsigned int flags; + ); + }; + """ + + kernel_doc = KernelDoc(self.config, "test.c", self.xforms) + patcher = patch('builtins.open', new_callable=mock_open, + read_data=dedent(source)) + with patcher: + _, entries = kernel_doc.parse_kdoc() + + self.assertEqual(len(entries), 1) + self.assertEqual(entries[0].warnings, []) + + # # Class and logic to create dynamic tests from YAML #
--
2.43.0