scsi: Fix the kerneldoc for scsi_initialize_rq()

Message ID 20170824161109.6e23432b@lwn.net
State New
Headers show
Series
  • scsi: Fix the kerneldoc for scsi_initialize_rq()
Related show

Commit Message

Jonathan Corbet Aug. 24, 2017, 10:11 p.m.
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(+)

-- 
2.13.4

Comments

Bart Van Assche Aug. 24, 2017, 11:26 p.m. | #1
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.
Martin K. Petersen Aug. 25, 2017, 9:39 p.m. | #2
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

Patch

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().
  */