Em Thu, 5 Nov 2020 15:00:17 +0000 Matthew Wilcox <willy@xxxxxxxxxxxxx> escreveu: > On Fri, Oct 23, 2020 at 06:33:43PM +0200, Mauro Carvalho Chehab wrote: > > Kernel-doc currently expects that the kernel-doc markup to come > > just before the function/enum/struct/union/typedef prototype. > > > > Yet, if it find things like: > > > > /** > > * refcount_add - add a value to a refcount > > * @i: the value to add to the refcount > > * @r: the refcount > > */ > > static inline void __refcount_add(int i, refcount_t *r, int *oldp); > > static inline void refcount_add(int i, refcount_t *r); > > > > Kernel-doc will do the wrong thing: > > 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? Matthew, As patches are usually generated with -U3, the context lines are not enough to show if a comment preceding a function is a kernel-doc markup or a normal comment. In practice, on some patches at this series, I found real issues because something else was added between the kernel-doc markup and the documented function. So, for me, it sounds a bad idea to remove the function name, as this can be used to detect such issues. Thanks, Mauro
