| Message ID | 20211203064820.27033-1-rdunlap@infradead.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | btrfs: zoned: convert comment to kernel-doc format | expand |
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).
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.
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.
--- 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 *
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(-)