[PATCH] fs/hfsplus: wrapper.c: fix kernel-doc warnings

[PATCH] fs/hfsplus: wrapper.c: fix kernel-doc warnings

[Randy Dunlap]

Fix kernel-doc warnings found when using "W=1".

wrapper.c:48: warning: No description found for return value of 'hfsplus_submit_bio'
wrapper.c:49: warning: Function parameter or member 'opf' not described in 'hfsplus_submit_bio'
wrapper.c:49: warning: Excess function parameter 'op' description in 'hfsplus_submit_bio'
wrapper.c:49: warning: Excess function parameter 'op_flags' description in 'hfsplus_submit_bio'

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: linux-fsdevel@vger.kernel.org
Cc: Alexander Viro <viro@zeniv.linux.org.uk>
Cc: Christian Brauner <brauner@kernel.org>
Cc: Jens Axboe <axboe@kernel.dk>
---
 fs/hfsplus/wrapper.c |    5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff -- a/fs/hfsplus/wrapper.c b/fs/hfsplus/wrapper.c
--- a/fs/hfsplus/wrapper.c
+++ b/fs/hfsplus/wrapper.c
@@ -30,8 +30,7 @@ struct hfsplus_wd {
  * @sector: block to read or write, for blocks of HFSPLUS_SECTOR_SIZE bytes
  * @buf: buffer for I/O
  * @data: output pointer for location of requested data
- * @op: direction of I/O
- * @op_flags: request op flags
+ * @opf: request op flags
  *
  * The unit of I/O is hfsplus_min_io_size(sb), which may be bigger than
  * HFSPLUS_SECTOR_SIZE, and @buf must be sized accordingly. On reads
@@ -43,6 +42,8 @@ struct hfsplus_wd {
  * that starts at the rounded-down address. As long as the data was
  * read using hfsplus_submit_bio() and the same buffer is used things
  * will work correctly.
+ *
+ * Returns: %0 on success else -errno code
  */
 int hfsplus_submit_bio(struct super_block *sb, sector_t sector,
 		       void *buf, void **data, blk_opf_t opf)

Re: [PATCH] fs/hfsplus: wrapper.c: fix kernel-doc warnings

[Christian Brauner]

On Tue, 05 Dec 2023 18:43:17 -0800, Randy Dunlap wrote:
> Fix kernel-doc warnings found when using "W=1".
> 
> wrapper.c:48: warning: No description found for return value of 'hfsplus_submit_bio'
> wrapper.c:49: warning: Function parameter or member 'opf' not described in 'hfsplus_submit_bio'
> wrapper.c:49: warning: Excess function parameter 'op' description in 'hfsplus_submit_bio'
> wrapper.c:49: warning: Excess function parameter 'op_flags' description in 'hfsplus_submit_bio'
> 
> [...]

Applied to the vfs.misc branch of the vfs/vfs.git tree.
Patches in the vfs.misc branch should appear in linux-next soon.

Please report any outstanding bugs that were missed during review in a
new review to the original patch series allowing us to drop it.

It's encouraged to provide Acked-bys and Reviewed-bys even though the
patch has now been applied. If possible patch trailers will be updated.

Note that commit hashes shown below are subject to change due to rebase,
trailer updates or similar. If in doubt, please check the listed branch.

tree:   https://git.kernel.org/pub/scm/linux/kernel/git/vfs/vfs.git
branch: vfs.misc

[1/1] fs/hfsplus: wrapper.c: fix kernel-doc warnings
      https://git.kernel.org/vfs/vfs/c/bff713c4a439

Re: [PATCH] fs/hfsplus: wrapper.c: fix kernel-doc warnings

[Bart Van Assche]

On 12/5/23 18:43, Randy Dunlap wrote:
> - * @op: direction of I/O
> - * @op_flags: request op flags
> + * @opf: request op flags

(just noticed this patch)

The new comment is worse than the original comments. This would be a
better explanation of the 'opf' argument:

+ * @opf: I/O operation type and flags

Thanks,

Bart.

Re: [PATCH] fs/hfsplus: wrapper.c: fix kernel-doc warnings

[Randy Dunlap]

On 2/9/24 13:57, Bart Van Assche wrote:
> On 12/5/23 18:43, Randy Dunlap wrote:
>> - * @op: direction of I/O
>> - * @op_flags: request op flags
>> + * @opf: request op flags
> 
> (just noticed this patch)
> 
> The new comment is worse than the original comments. This would be a
> better explanation of the 'opf' argument:
> 
> + * @opf: I/O operation type and flags

Agreed. I'll send an update.

thanks.
-- 
#Randy