[PATCH] btrfs: zoned: convert comment to kernel-doc format

[PATCH] btrfs: zoned: convert comment to kernel-doc format

[Randy Dunlap]

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

Fixes: afba2bc036b0 ("btrfs: zoned: implement active zone tracking")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Reported-by: kernel test robot <lkp@intel.com>
Cc: Naohiro Aota <naohiro.aota@wdc.com>
Cc: David Sterba <dsterba@suse.com>
Cc: Chris Mason <clm@fb.com>
Cc: Josef Bacik <josef@toxicpanda.com>
Cc: linux-btrfs@vger.kernel.org
---
 fs/btrfs/zoned.c |    2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

--- linux-next-20211202.orig/fs/btrfs/zoned.c
+++ linux-next-20211202/fs/btrfs/zoned.c
@@ -1781,7 +1781,7 @@ struct btrfs_device *btrfs_zoned_get_dev
 }
 
 /**
- * Activate block group and underlying device zones
+ * btrfs_zone_activate - Activate block group and underlying device zones
  *
  * @block_group: the block group to activate
  *

Re: [PATCH] btrfs: zoned: convert comment to kernel-doc format

[David Sterba]

On Thu, Dec 02, 2021 at 10:48:20PM -0800, Randy Dunlap wrote:
> 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,
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).

Re: [PATCH] btrfs: zoned: convert comment to kernel-doc format

[Randy Dunlap]

On 12/7/21 11:48, David Sterba wrote:
> On Thu, Dec 02, 2021 at 10:48:20PM -0800, Randy Dunlap wrote:
>> 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.

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

thanks.
-- 
~Randy

Re: [PATCH] btrfs: zoned: convert comment to kernel-doc format

[David Sterba]

On Tue, Dec 07, 2021 at 04:43:15PM -0800, Randy Dunlap wrote:
> On 12/7/21 11:48, David Sterba wrote:
> > On Thu, Dec 02, 2021 at 10:48:20PM -0800, Randy Dunlap wrote:
> >> 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.

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