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@xxxxxxxxxx>
> ---
> 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
>
