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

[Randy Dunlap]

On 9/26/26 8:16 AM, Jonathan Corbet wrote:
> Omokefe Emmanuel Onanaroghene <emmaonana18@xxxxxxxxx> 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.

While Bart's patch could work as a short-term/stopgap/workaround solution,
I also prefer the longer term solution of fixing the tools.

-- 
~Randy