[PATCH v2] PCI: endpoint: pci-epf-vntb: fix doc warning in pci-epf-vntb.c

[PATCH v2] PCI: endpoint: pci-epf-vntb: fix doc warning in pci-epf-vntb.c

[Yang Yingliang]

Fix the following make W=1 warning:

  drivers/pci/endpoint/functions/pci-epf-vntb.c:645: warning: Function parameter or member 'num_mws' not described in 'epf_ntb_mw_bar_clear'

Fixes: 8e4bfbe644a6 ("PCI: endpoint: pci-epf-vntb: fix error handle in epf_ntb_mw_bar_init()")
Signed-off-by: Yang Yingliang <yangyingliang@huawei.com>
---
v1 -> v2:
  Based on latest commit.
---
 drivers/pci/endpoint/functions/pci-epf-vntb.c | 1 +
 1 file changed, 1 insertion(+)

diff --git a/drivers/pci/endpoint/functions/pci-epf-vntb.c b/drivers/pci/endpoint/functions/pci-epf-vntb.c
index 04698e7995a5..37134aead77c 100644
--- a/drivers/pci/endpoint/functions/pci-epf-vntb.c
+++ b/drivers/pci/endpoint/functions/pci-epf-vntb.c
@@ -594,6 +594,7 @@ static void epf_ntb_db_bar_clear(struct epf_ntb *ntb)
 /**
  * epf_ntb_mw_bar_init() - Configure Memory window BARs
  * @ntb: NTB device that facilitates communication between HOST and VHOST
+ * @num_mws: the number of Memory window BARs that to be cleared
  *
  * Returns: Zero for success, or an error code in case of failure
  */
-- 
2.25.1

Re: [PATCH v2] PCI: endpoint: pci-epf-vntb: fix doc warning in pci-epf-vntb.c

[Bjorn Helgaas]

Hi Yang,

On Thu, Dec 22, 2022 at 11:43:24AM +0800, Yang Yingliang wrote:
> Fix the following make W=1 warning:
> 
>   drivers/pci/endpoint/functions/pci-epf-vntb.c:645: warning: Function parameter or member 'num_mws' not described in 'epf_ntb_mw_bar_clear'

No big deal here, but I try to make subject lines and commit logs a
little more specific.  "Fix doc warning" doesn't give any real
information, but something like "Add num_mws kernel-doc" would.

No need to repeat "pci-epf-vntb" in the subject; one mention is
enough.

> Fixes: 8e4bfbe644a6 ("PCI: endpoint: pci-epf-vntb: fix error handle in epf_ntb_mw_bar_init()")
> Signed-off-by: Yang Yingliang <yangyingliang@huawei.com>
> ---
> v1 -> v2:
>   Based on latest commit.

What is "latest commit"?  A SHA1 would make this unambiguous.

> ---
>  drivers/pci/endpoint/functions/pci-epf-vntb.c | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/drivers/pci/endpoint/functions/pci-epf-vntb.c b/drivers/pci/endpoint/functions/pci-epf-vntb.c
> index 04698e7995a5..37134aead77c 100644
> --- a/drivers/pci/endpoint/functions/pci-epf-vntb.c
> +++ b/drivers/pci/endpoint/functions/pci-epf-vntb.c
> @@ -594,6 +594,7 @@ static void epf_ntb_db_bar_clear(struct epf_ntb *ntb)
>  /**
>   * epf_ntb_mw_bar_init() - Configure Memory window BARs
>   * @ntb: NTB device that facilitates communication between HOST and VHOST
> + * @num_mws: the number of Memory window BARs that to be cleared

This patch happens to apply cleanly on 1b929c02afd3 ("Linux 6.2-rc1"),
but I think the hunk gets applied in the wrong place.

8e4bfbe644a6 ("PCI: endpoint: pci-epf-vntb: fix error handle in
epf_ntb_mw_bar_init()") added a "num_mws" parameter to
epf_ntb_mw_bar_clear() but failed to add kernel-doc for num_mws.

This patch adds kernel-doc for num_mws on *epf_ntb_mw_bar_init()*,
which doesn't have a num_mws parameter, so after applying it, I see
*two* kernel-doc warnings:

  $ make W=1 drivers/pci/endpoint/functions/pci-epf-vntb.o
  drivers/pci/endpoint/functions/pci-epf-vntb.c:602: warning: Excess function parameter 'num_mws' description in 'epf_ntb_mw_bar_init'
  drivers/pci/endpoint/functions/pci-epf-vntb.c:658: warning: Function parameter or member 'num_mws' not described in 'epf_ntb_mw_bar_clear'

>   * Returns: Zero for success, or an error code in case of failure
>   */
> -- 
> 2.25.1
> 

Re: [PATCH v2] PCI: endpoint: pci-epf-vntb: fix doc warning in pci-epf-vntb.c

[Yang Yingliang]

Hi,

On 2022/12/31 3:38, Bjorn Helgaas wrote:
> Hi Yang,
>
> On Thu, Dec 22, 2022 at 11:43:24AM +0800, Yang Yingliang wrote:
>> Fix the following make W=1 warning:
>>
>>    drivers/pci/endpoint/functions/pci-epf-vntb.c:645: warning: Function parameter or member 'num_mws' not described in 'epf_ntb_mw_bar_clear'
> No big deal here, but I try to make subject lines and commit logs a
> little more specific.  "Fix doc warning" doesn't give any real
> information, but something like "Add num_mws kernel-doc" would.
>
> No need to repeat "pci-epf-vntb" in the subject; one mention is
> enough.
OK.
>
>> Fixes: 8e4bfbe644a6 ("PCI: endpoint: pci-epf-vntb: fix error handle in epf_ntb_mw_bar_init()")
>> Signed-off-by: Yang Yingliang <yangyingliang@huawei.com>
>> ---
>> v1 -> v2:
>>    Based on latest commit.
> What is "latest commit"?  A SHA1 would make this unambiguous.
It's 1b929c02afd3 Linux 6.2-rc1.
When I make v1, it also has warning in comment of 
epf_ntb_config_sspad_bar_clear(),
so I fix it in v1, but it was fixed later, so remove the fix code in v2.
>
>> ---
>>   drivers/pci/endpoint/functions/pci-epf-vntb.c | 1 +
>>   1 file changed, 1 insertion(+)
>>
>> diff --git a/drivers/pci/endpoint/functions/pci-epf-vntb.c b/drivers/pci/endpoint/functions/pci-epf-vntb.c
>> index 04698e7995a5..37134aead77c 100644
>> --- a/drivers/pci/endpoint/functions/pci-epf-vntb.c
>> +++ b/drivers/pci/endpoint/functions/pci-epf-vntb.c
>> @@ -594,6 +594,7 @@ static void epf_ntb_db_bar_clear(struct epf_ntb *ntb)
>>   /**
>>    * epf_ntb_mw_bar_init() - Configure Memory window BARs
>>    * @ntb: NTB device that facilitates communication between HOST and VHOST
>> + * @num_mws: the number of Memory window BARs that to be cleared
> This patch happens to apply cleanly on 1b929c02afd3 ("Linux 6.2-rc1"),
> but I think the hunk gets applied in the wrong place.
>
> 8e4bfbe644a6 ("PCI: endpoint: pci-epf-vntb: fix error handle in
> epf_ntb_mw_bar_init()") added a "num_mws" parameter to
> epf_ntb_mw_bar_clear() but failed to add kernel-doc for num_mws.
>
> This patch adds kernel-doc for num_mws on *epf_ntb_mw_bar_init()*,
> which doesn't have a num_mws parameter, so after applying it, I see
> *two* kernel-doc warnings:
>
>    $ make W=1 drivers/pci/endpoint/functions/pci-epf-vntb.o
>    drivers/pci/endpoint/functions/pci-epf-vntb.c:602: warning: Excess function parameter 'num_mws' description in 'epf_ntb_mw_bar_init'
>    drivers/pci/endpoint/functions/pci-epf-vntb.c:658: warning: Function parameter or member 'num_mws' not described in 'epf_ntb_mw_bar_clear'
Sorry, I sent a wrong patch, the comment should be added to 
epf_ntb_mw_bar_clear().
I will send a new version later.

Thanks,
Yang
>
>>    * Returns: Zero for success, or an error code in case of failure
>>    */
>> -- 
>> 2.25.1
>>
> .