On Tue, Dec 07, 2021 at 04:43:15PM -0800, Randy Dunlap wrote:

On 12/7/21 11:48, David Sterba wrote:

quoted

On Thu, Dec 02, 2021 at 10:48:20PM -0800, Randy Dunlap wrote:

quoted

Complete kernel-doc notation for btrfs_zone_activate() to prevent
kernel-doc warnings:

zoned.c:1784: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * Activate block group and underlying device zones
zoned.c:1784: warning: missing initial short description on line:
 * Activate block group and underlying device zones

We've been using a slightly different format than the strict kernel-doc,

I'm sorry to hear that.

I feels like the kdoc format is meant for generating documentation and
has some requirements that I do not consider too human friendly, like
mandating the function name AND the function description on the first
line no matter how long it is. I'd rather have something for developers
where first line is summary of what the function does and list of
parameters to verify.

quoted

in this cas the function name is not repeated (because it's right under
the comment), what we want is the argument list checks (order and
completeness).

Please just eliminate/prevent the warning then.
I don't care how it's done.

It used to work and got changed/broken in 52042e2db452 ("scripts:
kernel-doc: validate kernel-doc markup with the actual names"), we
actually wanted to enable kdoc checks by default in our local Makefile.

We were working on that with Nikolay and he asked Mauro if the function
name could be optional. No answer so we get the warnings.