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

[Marco Elver]

On Sat, 26 Sept 2026 at 20:41, Randy Dunlap <rdunlap@xxxxxxxxxxxxx> wrote:
>
>
>
> 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.

Having more robust tools would be my preference, too. I'd like both
styles to be properly supported.

Acked-by: Marco Elver <elver@xxxxxxxxxx>