[PATCH] scsi: Fix the kerneldoc for scsi_initialize_rq()

[PATCH] scsi: Fix the kerneldoc for scsi_initialize_rq()

[Jonathan Corbet]

The kerneldoc comment for scsi_initialize_rq() neglected to document the
"rq" parameter, leading to this docs build warning:

  ./drivers/scsi/scsi_lib.c:1116: warning: No description found for parameter 'rq'

Document the parameter and make the build slightly quieter.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 drivers/scsi/scsi_lib.c | 1 +
 1 file changed, 1 insertion(+)

diff --git a/drivers/scsi/scsi_lib.c b/drivers/scsi/scsi_lib.c
index f6097b89d5d3..a76515814ee7 100644
--- a/drivers/scsi/scsi_lib.c
+++ b/drivers/scsi/scsi_lib.c
@@ -1108,6 +1108,7 @@ EXPORT_SYMBOL(scsi_init_io);
 
 /**
  * scsi_initialize_rq - initialize struct scsi_cmnd.req
+ * @rq: Request used to locate the scsi_cmnd structure.
  *
  * Called from inside blk_get_request().
  */
-- 
2.13.4

Re: [PATCH] scsi: Fix the kerneldoc for scsi_initialize_rq()

[Bart Van Assche]

On Thu, 2017-08-24 at 16:11 -0600, Jonathan Corbet wrote:
>  /**
>   * scsi_initialize_rq - initialize struct scsi_cmnd.req
> + * @rq: Request used to locate the scsi_cmnd structure.
>   *
>   * Called from inside blk_get_request().
>   */

Since the request structure and the SCSI command structure are adjacent,
how about the following:

@rq: Request associated with the SCSI command to be initialized.

Thanks,

Bart.

Re: [PATCH] scsi: Fix the kerneldoc for scsi_initialize_rq()

[Martin K. Petersen]

Jonathan,

> The kerneldoc comment for scsi_initialize_rq() neglected to document
> the "rq" parameter, leading to this docs build warning:

Applied to 4.14/scsi-queue. Tweaked the wording based on Bart's
comments. Thank you!

-- 
Martin K. Petersen	Oracle Linux Engineering