[PATCH] docs: kdoc: parse context_lock_struct() as struct declaration

[PATCH] docs: kdoc: parse context_lock_struct() as struct declaration

[Omokefe Emmanuel Onanaroghene]

kernel-doc fails to parse struct declarations wrapped in
context_lock_struct(), e.g. struct debugfs_cancellation:

  include/linux/debugfs.h:245 ... error: Cannot parse struct or union!

Add a struct transform that expands context_lock_struct() to a plain
struct declaration, and apply the struct transforms to the whole
declaration before split_struct_proto(), matching what dump_var() and
dump_function() already do for their prototypes. The member-only
transform in dump_struct() is then redundant.

Add a regression test for the debugfs_cancellation declaration.

Fixes: 6e530e2e3119 ("debugfs: Make debugfs_cancellation a context lock struct")
Signed-off-by: Omokefe Emmanuel Onanaroghene <emmaonana18@gmail.com>
---
 tools/lib/python/kdoc/kdoc_parser.py  | 11 +++++++----
 tools/lib/python/kdoc/xforms_lists.py |  1 +
 tools/unittests/test_kdoc_parser.py   | 26 ++++++++++++++++++++++++++
 3 files changed, 34 insertions(+), 4 deletions(-)

diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
index d9ad1ddc87dd..80d4245acd17 100644
--- a/tools/lib/python/kdoc/kdoc_parser.py
+++ b/tools/lib/python/kdoc/kdoc_parser.py
@@ -831,6 +831,13 @@ class KernelDoc:
         #
         source = source
         proto = trim_private_members(proto)
+
+        #
+        # Expand macro-based declarations, like context_lock_struct(),
+        # into a plain struct/union declaration before splitting it,
+        # as dump_var() and dump_function() already do.
+        #
+        proto = self.xforms.apply("struct", proto)
         struct_parts = self.split_struct_proto(proto)
         if not struct_parts:
             self.emit_msg(ln, f"{proto} error: Cannot parse struct or union!")
@@ -841,10 +848,6 @@ class KernelDoc:
             self.emit_msg(ln, f"expecting prototype for {decl_type} {self.entry.identifier}. "
                           f"Prototype was for {decl_type} {declaration_name} instead")
             return
-        #
-        # Go through the list of members applying all of our transformations.
-        #
-        members = self.xforms.apply("struct", members)
 
         #
         # Deal with embedded struct and union members, and drop enums entirely.
diff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/xforms_lists.py
index e3dda2fe8a53..9f2c750a811b 100644
--- a/tools/lib/python/kdoc/xforms_lists.py
+++ b/tools/lib/python/kdoc/xforms_lists.py
@@ -62,6 +62,7 @@ class CTransforms:
         (CMatch("struct_group_attr"), r"struct { \3+ };"),
         (CMatch("struct_group_tagged"), r"struct { \3+ };"),
         (CMatch("__struct_group"), r"struct { \4+ };"),
+        (CMatch("context_lock_struct"), r"struct \1"),
     ]
 
     #: Transforms for function prototypes.
diff --git a/tools/unittests/test_kdoc_parser.py b/tools/unittests/test_kdoc_parser.py
index c4a76ed13dbc..4baa78ca02b3 100755
--- a/tools/unittests/test_kdoc_parser.py
+++ b/tools/unittests/test_kdoc_parser.py
@@ -418,6 +418,32 @@ class TestSelfValidate(GenerateKdocItem):
         """
         self.run_test(self.SOURCE, [self.DEFAULT.copy()], self.EXPORTS)
 
+class TestContextLockStruct(GenerateKdocItem):
+    def test_context_lock_struct_declaration(self):
+        source = """
+            /**
+             * struct debugfs_cancellation - cancellation data
+             * @list: internal, for keeping track
+             * @cancel: callback to call
+             * @cancel_data: extra data for the callback to call
+             */
+            context_lock_struct(debugfs_cancellation) {
+                struct list_head list;
+                void (*cancel)(struct dentry *, void *);
+                void *cancel_data;
+            };
+        """
+
+        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].name, "debugfs_cancellation")
+        self.assertEqual(entries[0].warnings, [])
+
 #
 # Class and logic to create dynamic tests from YAML
 #
-- 
2.43.0

Re: [PATCH] docs: kdoc: parse context_lock_struct() as struct declaration

[Bart Van Assche]

On 9/25/26 4:40 PM, Omokefe Emmanuel Onanaroghene wrote:
> kernel-doc fails to parse struct declarations wrapped in
> context_lock_struct(), e.g. struct debugfs_cancellation:

Has this alternative been considered: instead of modifying
tools/lib/python/kdoc/kdoc_parser.py, apply the following change:

diff --git a/include/linux/debugfs.h b/include/linux/debugfs.h
index 4177c4738282..aa591f0b0920 100644
--- a/include/linux/debugfs.h
+++ b/include/linux/debugfs.h
@@ -233,13 +233,14 @@ ssize_t debugfs_write_file_bool(struct file *file, 
const char __user *user_buf,
  ssize_t debugfs_read_file_str(struct file *file, char __user *user_buf,
  			      size_t count, loff_t *ppos);

+context_lock_struct(debugfs_cancellation);
  /**
   * struct debugfs_cancellation - cancellation data
   * @list: internal, for keeping track
   * @cancel: callback to call
   * @cancel_data: extra data for the callback to call
   */
-context_lock_struct(debugfs_cancellation) {
+struct debugfs_cancellation {
  	struct list_head list;
  	void (*cancel)(struct dentry *, void *);
  	void *cancel_data;

Thanks,

Bart.

Re: [PATCH] docs: kdoc: parse context_lock_struct() as struct declaration

[Randy Dunlap]

On 9/25/26 5:14 PM, Bart Van Assche wrote:
> On 9/25/26 4:40 PM, Omokefe Emmanuel Onanaroghene wrote:
>> kernel-doc fails to parse struct declarations wrapped in
>> context_lock_struct(), e.g. struct debugfs_cancellation:
> 
> Has this alternative been considered: instead of modifying
> tools/lib/python/kdoc/kdoc_parser.py, apply the following change:

I don't think that has been tried/considered.
I'm OK with it if Marco & Peter are.

> diff --git a/include/linux/debugfs.h b/include/linux/debugfs.h
> index 4177c4738282..aa591f0b0920 100644
> --- a/include/linux/debugfs.h
> +++ b/include/linux/debugfs.h
> @@ -233,13 +233,14 @@ ssize_t debugfs_write_file_bool(struct file *file, const char __user *user_buf,
>  ssize_t debugfs_read_file_str(struct file *file, char __user *user_buf,
>                    size_t count, loff_t *ppos);
> 
> +context_lock_struct(debugfs_cancellation);
>  /**
>   * struct debugfs_cancellation - cancellation data
>   * @list: internal, for keeping track
>   * @cancel: callback to call
>   * @cancel_data: extra data for the callback to call
>   */
> -context_lock_struct(debugfs_cancellation) {
> +struct debugfs_cancellation {
>      struct list_head list;
>      void (*cancel)(struct dentry *, void *);
>      void *cancel_data;
> 
> Thanks,
> 
> Bart.

thanks.
-- 
~Randy

Re: [PATCH] docs: kdoc: parse context_lock_struct() as struct declaration

[Omokefe Emmanuel Onanaroghene]

Hi Bart,

> Has this alternative been considered: instead of modifying
> tools/lib/python/kdoc/kdoc_parser.py, apply the following change:

Thanks for taking the time to review this. I tried your split
(`context_lock_struct()` above the comment, plain `struct` below), and it
does fix the warning.

> +context_lock_struct(debugfs_cancellation);
> ...
> -context_lock_struct(debugfs_cancellation) {
> +struct debugfs_cancellation {

I still think the tool-side fix is the better route: `debugfs_cancellation`
is the only one with a kernel-doc comment today, but the next comment
added above any of the others would hit the same error, and we'd be
fixing the same warning again.

The part that really sold me on changing the tool was a general ordering
issue in `dump_struct()`: unlike `dump_var()` and `dump_function()`, it
applied the transforms only to the members after `split_struct_proto()`,
so they could never repair the declaration line itself. Moving the
transform earlier fixes that, and a full-tree A/B test removes the
existing warning without adding any new ones.

Would you and Marco prefer the tool-side fix, or should I respin with the
`debugfs.h` change?

Thanks,

Omokefe

Re: [PATCH] docs: kdoc: parse context_lock_struct() as struct declaration

[Jonathan Corbet]

Omokefe Emmanuel Onanaroghene <emmaonana18@gmail.com> writes:

>> +context_lock_struct(debugfs_cancellation);
>> ...
>> -context_lock_struct(debugfs_cancellation) {
>> +struct debugfs_cancellation {
>
> I still think the tool-side fix is the better route: `debugfs_cancellation`
> is the only one with a kernel-doc comment today, but the next comment
> added above any of the others would hit the same error, and we'd be
> fixing the same warning again.
>
> The part that really sold me on changing the tool was a general ordering
> issue in `dump_struct()`: unlike `dump_var()` and `dump_function()`, it
> applied the transforms only to the members after `split_struct_proto()`,
> so they could never repair the declaration line itself. Moving the
> transform earlier fixes that, and a full-tree A/B test removes the
> existing warning without adding any new ones.
>
> Would you and Marco prefer the tool-side fix, or should I respin with the
> `debugfs.h` change?

I think that making the docs tools more robust, and avoiding the forcing
of code changes to make the tools happy, are good things, so I am
inclined to accept this change.

Omokefe, I have to ask: did you write this patch yourself, or was there
LLM assistance as well?  In the latter case, it needs an Assisted-by
tag.

Thanks,

jon

Re: [PATCH] docs: kdoc: parse context_lock_struct() as struct declaration

[Omokefe Emmanuel Onanaroghene]

Hi Jon,

On 9/26/26 9:16 AM, Jonathan Corbet wrote:
> Omokefe, I have to ask: did you write this patch yourself, or was there
> LLM assistance as well?  In the latter case, it needs an Assisted-by
> tag.

Yes, I did write this patch myself 
I have also added Assisted-by tag to my first patch V2: https://lore.kernel.org/all/20260916214357.22573-1-emmaonana18@gmail.com,
as you requested.

Thank you for taking the time and for being open to 
the tool-side approach.

Thanks,

Omokefe

Re: [PATCH] docs: kdoc: parse context_lock_struct() as struct declaration

[Jonathan Corbet]

Omokefe Emmanuel Onanaroghene <emmaonana18@gmail.com> writes:

> Hi Jon,
>
> On 9/26/26 9:16 AM, Jonathan Corbet wrote:
>> Omokefe, I have to ask: did you write this patch yourself, or was there
>> LLM assistance as well?  In the latter case, it needs an Assisted-by
>> tag.
>
> Yes, I did write this patch myself 
> I have also added Assisted-by tag to my first patch V2: https://lore.kernel.org/all/20260916214357.22573-1-emmaonana18@gmail.com,
> as you requested.

Ah OK, apologies for asking you again.  Keeping up with the world is
proving challenging at the moment...

Thanks,

jon