Re: [PATCH v3 56/56] scrpits: kernel-doc: validate kernel-doc markup with the actual names

Matthew Wilcox
2020-11-05T15:30:35Z

On Thu, Nov 05, 2020 at 08:15:26AM -0700, Jonathan Corbet wrote:
> On Thu, 5 Nov 2020 15:00:17 +0000
> Matthew Wilcox <willy@infradead.org> wrote:
>
> > I wonder if we could change kernel-doc to be (optionally) less verbose.
> > If we allowed people to write:
> >
> > /**
> > * Add a value to a refcount.
> > * @i: The value to add to the refcount
> > * @r: The refcount
> > */
> >
> > and had the kernel-doc script pick up the name of the following function
> > automatically, would that be an improvement we could all agree on?
>
> Given the number of issues Mauro just fixed where the comments had become
> separated from the functions they documented, this seems potentially
> hazardous... It seems especially likely to fail with the "change foo() to
> __foo() and add a new foo() down below" pattern that is fairly common.

Sort of, yes. The usual case for doing that is where one adds a new
parameter, and kernel-doc will warn about that. But if the parameters
stay the same (eg refcount_add takes a lock and __refcount_add assumes
the lock is already held), then you've got documentation of __refcount_add
and no documentation of refcount_add() ... and it's probably still _true_
documentation, just not as useful.