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

Jonathan Corbet
2020-11-05T15:15:29Z

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.

jon