diff mbox series

[v2,01/12] scsi: core: Suppress a kernel-doc warning

Message ID 20211129194609.3466071-2-bvanassche@acm.org
State Superseded
Headers show
Series A series of small SCSI patches | expand

Commit Message

Bart Van Assche Nov. 29, 2021, 7:45 p.m. UTC
Suppress the following kernel-doc warning:

drivers/scsi/scsi_scan.c:129: warning: Function parameter or member 'dev' not described in 'scsi_enable_async_suspend'

Fixes: a19a93e4c6a9 ("scsi: core: pm: Rely on the device driver core for async power management")
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Signed-off-by: Bart Van Assche <bvanassche@acm.org>
---
 drivers/scsi/scsi_scan.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

Comments

Randy Dunlap Dec. 13, 2021, 2:53 a.m. UTC | #1
Hi Bart, Martin,

On 11/29/21 11:45, Bart Van Assche wrote:
> Suppress the following kernel-doc warning:
> 
> drivers/scsi/scsi_scan.c:129: warning: Function parameter or member 'dev' not described in 'scsi_enable_async_suspend'
> 
> Fixes: a19a93e4c6a9 ("scsi: core: pm: Rely on the device driver core for async power management")
> Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> Signed-off-by: Bart Van Assche <bvanassche@acm.org>
> ---
>  drivers/scsi/scsi_scan.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/drivers/scsi/scsi_scan.c b/drivers/scsi/scsi_scan.c
> index 23e1c0acdeae..2f80509fa036 100644
> --- a/drivers/scsi/scsi_scan.c
> +++ b/drivers/scsi/scsi_scan.c
> @@ -122,7 +122,7 @@ struct async_scan_data {
>  	struct completion prev_finished;
>  };
>  
> -/**
> +/*
>   * scsi_enable_async_suspend - Enable async suspend and resume
>   */
>  void scsi_enable_async_suspend(struct device *dev)
> 

Why this instead of describing @dev: ?

 * @dev: the struct device to enable for async suspend and resume


thanks.
Bart Van Assche Dec. 13, 2021, 3:03 a.m. UTC | #2
On 12/12/21 18:53, Randy Dunlap wrote:
> On 11/29/21 11:45, Bart Van Assche wrote:
>> -/**
>> +/*
>>    * scsi_enable_async_suspend - Enable async suspend and resume
>>    */
>>   void scsi_enable_async_suspend(struct device *dev)
>>
> 
> Why this instead of describing @dev: ?
> 
>   * @dev: the struct device to enable for async suspend and resume

Hi Randy,

I expect that anyone can guess the meaning of the @dev argument without 
adding any explanation. Hence the choice to convert the kernel-doc 
comment into a regular comment.

Thanks,

Bart.
Randy Dunlap Dec. 13, 2021, 3:06 a.m. UTC | #3
On 12/12/21 19:03, Bart Van Assche wrote:
> On 12/12/21 18:53, Randy Dunlap wrote:
>> On 11/29/21 11:45, Bart Van Assche wrote:
>>> -/**
>>> +/*
>>>    * scsi_enable_async_suspend - Enable async suspend and resume
>>>    */
>>>   void scsi_enable_async_suspend(struct device *dev)
>>>
>>
>> Why this instead of describing @dev: ?
>>
>>   * @dev: the struct device to enable for async suspend and resume
> 
> Hi Randy,
> 
> I expect that anyone can guess the meaning of the @dev argument without adding any explanation. Hence the choice to convert the kernel-doc comment into a regular comment.

That's probably true, but we do try to document (using kernel-doc)
non-static functions for other people's use.

Oh well. Thanks.
diff mbox series

Patch

diff --git a/drivers/scsi/scsi_scan.c b/drivers/scsi/scsi_scan.c
index 23e1c0acdeae..2f80509fa036 100644
--- a/drivers/scsi/scsi_scan.c
+++ b/drivers/scsi/scsi_scan.c
@@ -122,7 +122,7 @@  struct async_scan_data {
 	struct completion prev_finished;
 };
 
-/**
+/*
  * scsi_enable_async_suspend - Enable async suspend and resume
  */
 void scsi_enable_async_suspend(struct device *dev)