[PATCH] block: improve kerneldoc of blk_mq_add_to_batch()

[PATCH] block: improve kerneldoc of blk_mq_add_to_batch()

[Shin'ichiro Kawasaki]

Commit f00baf2eac78 ("block: change blk_mq_add_to_batch() third argument
type to bool") added kerneldoc style comment of blk_mq_add_to_batch().
However, it did not follow the kerneldoc format and was incomplete.
Improve the comment to follow the format.

Signed-off-by: Shin'ichiro Kawasaki <shinichiro.kawasaki@wdc.com>
---
This is the follow-up fix for the patch titled "[PATCH v2 0/2] block: nvme: fix
blktests nvme/039 failure" [1]. Reviews will be appreciated.

I ran the command

  $ scripts/kernel-doc -v include/linux/blk-mq.h

and confirmed the modified comment follows the kerneldoc format.

[1] https://lore.kernel.org/linux-block/20250311104359.1767728-3-shinichiro.kawasaki@wdc.com/

 include/linux/blk-mq.h | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/include/linux/blk-mq.h b/include/linux/blk-mq.h
index d904e870e72d..aba9c24486aa 100644
--- a/include/linux/blk-mq.h
+++ b/include/linux/blk-mq.h
@@ -852,14 +852,17 @@ static inline bool blk_mq_is_reserved_rq(struct request *rq)
 	return rq->rq_flags & RQF_RESV;
 }
 
-/*
- * Batched completions only work when there is no I/O error and no special
- * ->end_io handler.
- *
+/**
+ * blk_mq_add_to_batch() - add a request to the completion batch
  * @req: The request to add to batch
  * @iob: The batch to add the request
  * @is_error: Specify true if the request failed with an error
- * @io_comp_batch: The completaion handler for the request
+ * @complete: The completaion handler for the request
+ *
+ * Batched completions only work when there is no I/O error and no special
+ * ->end_io handler.
+ *
+ * Return: true when the request was added to the batch, otherwise false
  */
 static inline bool blk_mq_add_to_batch(struct request *req,
 				       struct io_comp_batch *iob, bool is_error,
-- 
2.47.0

Re: [PATCH] block: improve kerneldoc of blk_mq_add_to_batch()

[Christoph Hellwig]

Looks good:

Reviewed-by: Christoph Hellwig <hch@lst.de>

Re: [PATCH] block: improve kerneldoc of blk_mq_add_to_batch()

[Jens Axboe]

On 3/12/25 1:27 AM, Shin'ichiro Kawasaki wrote:
> Commit f00baf2eac78 ("block: change blk_mq_add_to_batch() third argument
> type to bool") added kerneldoc style comment of blk_mq_add_to_batch().
> However, it did not follow the kerneldoc format and was incomplete.
> Improve the comment to follow the format.

Thanks, I'll fold this in to the other patch.

-- 
Jens Axboe

Re: [PATCH] block: improve kerneldoc of blk_mq_add_to_batch()

[Jens Axboe]

On Wed, 12 Mar 2025 16:27:12 +0900, Shin'ichiro Kawasaki wrote:
> Commit f00baf2eac78 ("block: change blk_mq_add_to_batch() third argument
> type to bool") added kerneldoc style comment of blk_mq_add_to_batch().
> However, it did not follow the kerneldoc format and was incomplete.
> Improve the comment to follow the format.
> 
> 

Applied, thanks!

[1/1] block: improve kerneldoc of blk_mq_add_to_batch()
      (no commit info)

Best regards,
-- 
Jens Axboe