[PATCH] scsi_dh: Document alua_rtpg_queue() arguments

[PATCH] scsi_dh: Document alua_rtpg_queue() arguments

[Bart Van Assche]

Since commit 3a025e1d1c2e ("Add optional check for bad kernel-doc
comments") building with W=1 causes warnings to appear for issues
in kernel-doc headers. This patch avoids that the following warnings
are reported when building with W=1:

drivers/scsi/device_handler/scsi_dh_alua.c:867: warning: No description found for parameter 'pg'
drivers/scsi/device_handler/scsi_dh_alua.c:867: warning: No description found for parameter 'sdev'
drivers/scsi/device_handler/scsi_dh_alua.c:867: warning: No description found for parameter 'qdata'
drivers/scsi/device_handler/scsi_dh_alua.c:867: warning: No description found for parameter 'force'

Signed-off-by: Bart Van Assche <bart.vanassche@wdc.com>
Cc: Christoph Hellwig <hch@lst.de>
Cc: Hannes Reinecke <hare@suse.com>
Cc: Johannes Thumshirn <jthumshirn@suse.de>
---
 drivers/scsi/device_handler/scsi_dh_alua.c | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/drivers/scsi/device_handler/scsi_dh_alua.c b/drivers/scsi/device_handler/scsi_dh_alua.c
index 022e421c2185..4b44325d1a82 100644
--- a/drivers/scsi/device_handler/scsi_dh_alua.c
+++ b/drivers/scsi/device_handler/scsi_dh_alua.c
@@ -876,6 +876,11 @@ static void alua_rtpg_work(struct work_struct *work)
 
 /**
  * alua_rtpg_queue() - cause RTPG to be submitted asynchronously
+ * @pg: ALUA port group associated with @sdev.
+ * @sdev: SCSI device for which to submit an RTPG.
+ * @qdata: Information about the callback to invoke after the RTPG.
+ * @force: Whether or not to submit an RTPG if a work item that will submit an
+ *         RTPG already has been scheduled.
  *
  * Returns true if and only if alua_rtpg_work() will be called asynchronously.
  * That function is responsible for calling @qdata->fn().
-- 
2.15.1

Re: [PATCH] scsi_dh: Document alua_rtpg_queue() arguments

[Hannes Reinecke]

On 01/24/2018 12:50 AM, Bart Van Assche wrote:
> Since commit 3a025e1d1c2e ("Add optional check for bad kernel-doc
> comments") building with W=1 causes warnings to appear for issues
> in kernel-doc headers. This patch avoids that the following warnings
> are reported when building with W=1:
> 
> drivers/scsi/device_handler/scsi_dh_alua.c:867: warning: No description found for parameter 'pg'
> drivers/scsi/device_handler/scsi_dh_alua.c:867: warning: No description found for parameter 'sdev'
> drivers/scsi/device_handler/scsi_dh_alua.c:867: warning: No description found for parameter 'qdata'
> drivers/scsi/device_handler/scsi_dh_alua.c:867: warning: No description found for parameter 'force'
> 
> Signed-off-by: Bart Van Assche <bart.vanassche@wdc.com>
> Cc: Christoph Hellwig <hch@lst.de>
> Cc: Hannes Reinecke <hare@suse.com>
> Cc: Johannes Thumshirn <jthumshirn@suse.de>
> ---
>  drivers/scsi/device_handler/scsi_dh_alua.c | 5 +++++
>  1 file changed, 5 insertions(+)
> 
> diff --git a/drivers/scsi/device_handler/scsi_dh_alua.c b/drivers/scsi/device_handler/scsi_dh_alua.c
> index 022e421c2185..4b44325d1a82 100644
> --- a/drivers/scsi/device_handler/scsi_dh_alua.c
> +++ b/drivers/scsi/device_handler/scsi_dh_alua.c
> @@ -876,6 +876,11 @@ static void alua_rtpg_work(struct work_struct *work)
>  
>  /**
>   * alua_rtpg_queue() - cause RTPG to be submitted asynchronously
> + * @pg: ALUA port group associated with @sdev.
> + * @sdev: SCSI device for which to submit an RTPG.
> + * @qdata: Information about the callback to invoke after the RTPG.
> + * @force: Whether or not to submit an RTPG if a work item that will submit an
> + *         RTPG already has been scheduled.
>   *
>   * Returns true if and only if alua_rtpg_work() will be called asynchronously.
>   * That function is responsible for calling @qdata->fn().
> 
Reviewed-by: Hannes Reinecke <hare@suse.com>

Cheers,

Hannes
-- 
Dr. Hannes Reinecke		               zSeries & Storage
hare@suse.com			               +49 911 74053 688
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg
GF: F. Imendörffer, J. Smithard, D. Upmanyu, G. Norton
HRB 21284 (AG Nürnberg)

Re: [PATCH] scsi_dh: Document alua_rtpg_queue() arguments

[Johannes Thumshirn]

Looks good,
Reviewed-by: Johannes Thumshirn <jthumshirn@suse.de>

Re: [PATCH] scsi_dh: Document alua_rtpg_queue() arguments

[Martin K. Petersen]

Bart,

> Since commit 3a025e1d1c2e ("Add optional check for bad kernel-doc
> comments") building with W=1 causes warnings to appear for issues
> in kernel-doc headers. This patch avoids that the following warnings
> are reported when building with W=1:

Applied to 4.16/scsi-fixes, thanks!

-- 
Martin K. Petersen	Oracle Linux Engineering