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(-)
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/
Fixes: 2f07ddbd5793 ("docs: xforms_lists: better evaluate struct_group macros")
Signed-off-by: Omokefe Emmanuel Onanaroghene <emmaonana18@gmail.com>
---
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.0Hi--
On 9/14/26 8:51 AM, Omokefe Emmanuel Onanaroghene wrote:
> 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/
> Fixes: 2f07ddbd5793 ("docs: xforms_lists: better evaluate struct_group macros")
> Signed-off-by: Omokefe Emmanuel Onanaroghene <emmaonana18@gmail.com>
> ---
> 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
> #
Would something similar to this work for this warning?
Warning: include/linux/debugfs.h:246 context_lock_struct(debugfs_cancellation) { struct list_head list; void (*cancel)(struct dentry *, void *); void *cancel_data; }; error: Cannot parse struct or union!
Even though context_lock_struct is in xforms_list.py, it's not working
in this case (above).
thanks.
--
~Randy
Omokefe Emmanuel Onanaroghene <emmaonana18@gmail.com> writes:
> 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/
> Fixes: 2f07ddbd5793 ("docs: xforms_lists: better evaluate struct_group macros")
> Signed-off-by: Omokefe Emmanuel Onanaroghene <emmaonana18@gmail.com>
> ---
> 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(-)
This seems perhaps a reasonable fix. Did you write this on your own, or
was there an LLM involved?
Thanks,
jon
On 9/14/26 8:51 AM, Omokefe Emmanuel Onanaroghene wrote:
> 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/
> Fixes: 2f07ddbd5793 ("docs: xforms_lists: better evaluate struct_group macros")
> Signed-off-by: Omokefe Emmanuel Onanaroghene <emmaonana18@gmail.com>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Thanks.
> ---
> 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
> #
--
~Randy
© 2016 - 2026 Red Hat, Inc.