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.
