[PATCH] fpga: dfl: fme: fix kernel-doc comments for some functions

[PATCH] fpga: dfl: fme: fix kernel-doc comments for some functions

[Peter Colberg]

From: Xu Yilun <yilun.xu@intel.com>

lkp reported 2 build warnings:

   drivers/fpga/dfl/dfl-fme-pr.c:175: warning: Function parameter or member 'feature' not described in 'dfl_fme_create_mgr'

>> drivers/fpga/dfl/dfl-fme-pr.c:280: warning: expecting prototype for
>> dfl_fme_destroy_bridge(). Prototype was for dfl_fme_destroy_bridges()
>> instead

Fixes: 29de76240e86 ("fpga: dfl: fme: add partial reconfiguration sub feature support")
Reported-by: kernel test robot <lkp@intel.com>
Signed-off-by: Xu Yilun <yilun.xu@intel.com>
Signed-off-by: Peter Colberg <peter.colberg@intel.com>
---
 drivers/fpga/dfl-fme-pr.c | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/drivers/fpga/dfl-fme-pr.c b/drivers/fpga/dfl-fme-pr.c
index cdcf6dea4cc9..96cb24787ab1 100644
--- a/drivers/fpga/dfl-fme-pr.c
+++ b/drivers/fpga/dfl-fme-pr.c
@@ -166,6 +166,7 @@ static int fme_pr(struct platform_device *pdev, unsigned long arg)
  * dfl_fme_create_mgr - create fpga mgr platform device as child device
  * @feature: sub feature info
  * @pdata: fme platform_device's pdata
+ * @feature: the dfl fme PR sub feature
  *
  * Return: mgr platform device if successful, and error code otherwise.
  */
@@ -273,7 +274,7 @@ static void dfl_fme_destroy_bridge(struct dfl_fme_bridge *fme_br)
 }
 
 /**
- * dfl_fme_destroy_bridges - destroy all fpga bridge platform device
+ * dfl_fme_destroy_bridges - destroy all fpga bridge platform devices
  * @pdata: fme platform device's pdata
  */
 static void dfl_fme_destroy_bridges(struct dfl_feature_platform_data *pdata)
-- 
2.44.0

Re: [PATCH] fpga: dfl: fme: fix kernel-doc comments for some functions

[Xu Yilun]

On Thu, Mar 28, 2024 at 08:15:42PM -0400, Peter Colberg wrote:
> From: Xu Yilun <yilun.xu@intel.com>

I didn't remember I wrote this exact patch, but anyway the patch itself
is confusing.

> 
> lkp reported 2 build warnings:
> 
>    drivers/fpga/dfl/dfl-fme-pr.c:175: warning: Function parameter or member 'feature' not described in 'dfl_fme_create_mgr'
> 
> >> drivers/fpga/dfl/dfl-fme-pr.c:280: warning: expecting prototype for
> >> dfl_fme_destroy_bridge(). Prototype was for dfl_fme_destroy_bridges()
> >> instead
> 
> Fixes: 29de76240e86 ("fpga: dfl: fme: add partial reconfiguration sub feature support")
> Reported-by: kernel test robot <lkp@intel.com>
> Signed-off-by: Xu Yilun <yilun.xu@intel.com>
> Signed-off-by: Peter Colberg <peter.colberg@intel.com>
> ---
>  drivers/fpga/dfl-fme-pr.c | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/drivers/fpga/dfl-fme-pr.c b/drivers/fpga/dfl-fme-pr.c
> index cdcf6dea4cc9..96cb24787ab1 100644
> --- a/drivers/fpga/dfl-fme-pr.c
> +++ b/drivers/fpga/dfl-fme-pr.c
> @@ -166,6 +166,7 @@ static int fme_pr(struct platform_device *pdev, unsigned long arg)
>   * dfl_fme_create_mgr - create fpga mgr platform device as child device
>   * @feature: sub feature info

The member 'feature' is described here. It still causes build warning?

>   * @pdata: fme platform_device's pdata
> + * @feature: the dfl fme PR sub feature

Why adding a duplicated item would fix the warning?

>   *
>   * Return: mgr platform device if successful, and error code otherwise.
>   */
> @@ -273,7 +274,7 @@ static void dfl_fme_destroy_bridge(struct dfl_fme_bridge *fme_br)
>  }
>  
>  /**
> - * dfl_fme_destroy_bridges - destroy all fpga bridge platform device

The prototype is for dfl_fme_destroy_bridges(), why the warning?

> + * dfl_fme_destroy_bridges - destroy all fpga bridge platform devices

Correct the plural form in description would fix the warning?

>   * @pdata: fme platform device's pdata
>   */
>  static void dfl_fme_destroy_bridges(struct dfl_feature_platform_data *pdata)
> -- 
> 2.44.0
> 
> 

Re: [PATCH] fpga: dfl: fme: fix kernel-doc comments for some functions

[Randy Dunlap]

On 4/1/24 8:47 PM, Xu Yilun wrote:
> On Thu, Mar 28, 2024 at 08:15:42PM -0400, Peter Colberg wrote:
>> From: Xu Yilun <yilun.xu@intel.com>
> 
> I didn't remember I wrote this exact patch, but anyway the patch itself
> is confusing.
> 
>>
>> lkp reported 2 build warnings:
>>
>>    drivers/fpga/dfl/dfl-fme-pr.c:175: warning: Function parameter or member 'feature' not described in 'dfl_fme_create_mgr'
>>
>>>> drivers/fpga/dfl/dfl-fme-pr.c:280: warning: expecting prototype for
>>>> dfl_fme_destroy_bridge(). Prototype was for dfl_fme_destroy_bridges()
>>>> instead
>>
>> Fixes: 29de76240e86 ("fpga: dfl: fme: add partial reconfiguration sub feature support")
>> Reported-by: kernel test robot <lkp@intel.com>
>> Signed-off-by: Xu Yilun <yilun.xu@intel.com>
>> Signed-off-by: Peter Colberg <peter.colberg@intel.com>

All kernel-doc issues with this source file are already fixed in linux-next
by this commit:

commit 782d8e61b5d6
Author: Randy Dunlap <rdunlap@infradead.org>
Date:   Thu Jan 12 22:37:20 2023 -0800

    fpga: dfl: kernel-doc corrections
    
    Fix W=1 kernel-doc warnings in drivers/fpga/:


>> ---
>>  drivers/fpga/dfl-fme-pr.c | 3 ++-
>>  1 file changed, 2 insertions(+), 1 deletion(-)
>>
>> diff --git a/drivers/fpga/dfl-fme-pr.c b/drivers/fpga/dfl-fme-pr.c
>> index cdcf6dea4cc9..96cb24787ab1 100644
>> --- a/drivers/fpga/dfl-fme-pr.c
>> +++ b/drivers/fpga/dfl-fme-pr.c
>> @@ -166,6 +166,7 @@ static int fme_pr(struct platform_device *pdev, unsigned long arg)
>>   * dfl_fme_create_mgr - create fpga mgr platform device as child device
>>   * @feature: sub feature info
> 
> The member 'feature' is described here. It still causes build warning?
> 
>>   * @pdata: fme platform_device's pdata
>> + * @feature: the dfl fme PR sub feature
> 
> Why adding a duplicated item would fix the warning?
> 
>>   *
>>   * Return: mgr platform device if successful, and error code otherwise.
>>   */
>> @@ -273,7 +274,7 @@ static void dfl_fme_destroy_bridge(struct dfl_fme_bridge *fme_br)
>>  }
>>  
>>  /**
>> - * dfl_fme_destroy_bridges - destroy all fpga bridge platform device
> 
> The prototype is for dfl_fme_destroy_bridges(), why the warning?
> 
>> + * dfl_fme_destroy_bridges - destroy all fpga bridge platform devices
> 
> Correct the plural form in description would fix the warning?
> 
>>   * @pdata: fme platform device's pdata
>>   */
>>  static void dfl_fme_destroy_bridges(struct dfl_feature_platform_data *pdata)
>> -- 
>> 2.44.0
>>
>>
> 

-- 
#Randy

Re: [PATCH] fpga: dfl: fme: fix kernel-doc comments for some functions

[Colberg, Peter]

On Mon, 2024-04-01 at 21:42 -0700, Randy Dunlap wrote:
> 
> On 4/1/24 8:47 PM, Xu Yilun wrote:
> > On Thu, Mar 28, 2024 at 08:15:42PM -0400, Peter Colberg wrote:
> > > From: Xu Yilun <yilun.xu@intel.com>
> > 
> > I didn't remember I wrote this exact patch, but anyway the patch itself
> > is confusing.

My apology, the original patch was indeed rebased incorrectly onto
commit 782d8e61b5d6 ("fpga: dfl: kernel-doc corrections").

> > 
> > > 
> > > lkp reported 2 build warnings:
> > > 
> > >    drivers/fpga/dfl/dfl-fme-pr.c:175: warning: Function parameter or member 'feature' not described in 'dfl_fme_create_mgr'
> > > 
> > > > > drivers/fpga/dfl/dfl-fme-pr.c:280: warning: expecting prototype for
> > > > > dfl_fme_destroy_bridge(). Prototype was for dfl_fme_destroy_bridges()
> > > > > instead
> > > 
> > > Fixes: 29de76240e86 ("fpga: dfl: fme: add partial reconfiguration sub feature support")
> > > Reported-by: kernel test robot <lkp@intel.com>
> > > Signed-off-by: Xu Yilun <yilun.xu@intel.com>
> > > Signed-off-by: Peter Colberg <peter.colberg@intel.com>
> 
> All kernel-doc issues with this source file are already fixed in linux-next
> by this commit:
> 
> commit 782d8e61b5d6
> Author: Randy Dunlap <rdunlap@infradead.org>
> Date:   Thu Jan 12 22:37:20 2023 -0800
> 
>     fpga: dfl: kernel-doc corrections
>     
>     Fix W=1 kernel-doc warnings in drivers/fpga/:
> 
> 
> > > ---
> > >  drivers/fpga/dfl-fme-pr.c | 3 ++-
> > >  1 file changed, 2 insertions(+), 1 deletion(-)
> > > 
> > > diff --git a/drivers/fpga/dfl-fme-pr.c b/drivers/fpga/dfl-fme-pr.c
> > > index cdcf6dea4cc9..96cb24787ab1 100644
> > > --- a/drivers/fpga/dfl-fme-pr.c
> > > +++ b/drivers/fpga/dfl-fme-pr.c
> > > @@ -166,6 +166,7 @@ static int fme_pr(struct platform_device *pdev, unsigned long arg)
> > >   * dfl_fme_create_mgr - create fpga mgr platform device as child device
> > >   * @feature: sub feature info
> > 
> > The member 'feature' is described here. It still causes build warning?
> > 
> > >   * @pdata: fme platform_device's pdata
> > > + * @feature: the dfl fme PR sub feature
> > 
> > Why adding a duplicated item would fix the warning?

Apologies for the confusion; commit 782d8e61b5d6 only changed the
function name to plural, which addresses the kernel-doc warning;
whereas your original patch also changed the description to plural.

I will send a revised, correctly rebased patch.

Thanks,
Peter

> > 
> > >   *
> > >   * Return: mgr platform device if successful, and error code otherwise.
> > >   */
> > > @@ -273,7 +274,7 @@ static void dfl_fme_destroy_bridge(struct dfl_fme_bridge *fme_br)
> > >  }
> > >  
> > >  /**
> > > - * dfl_fme_destroy_bridges - destroy all fpga bridge platform device
> > 
> > The prototype is for dfl_fme_destroy_bridges(), why the warning?
> > 
> > > + * dfl_fme_destroy_bridges - destroy all fpga bridge platform devices
> > 
> > Correct the plural form in description would fix the warning?
> > 
> > >   * @pdata: fme platform device's pdata
> > >   */
> > >  static void dfl_fme_destroy_bridges(struct dfl_feature_platform_data *pdata)
> > > -- 
> > > 2.44.0
> > > 
> > > 
> > 
>