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

[Matthew Wilcox]

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@xxxxxxxxxxxxx> 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.