Skip to contentSkip to conversation

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

PATCH Superseded Peter Colberg 3 participants 4 messages Mar 29, 2024 – Apr 2, 2024

Subsystems (2)

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 fpga: dfl: fme: fix kernel-doc comments for some functions

From: Xu Yilun <[email protected]>

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'

Quoted 3 lines
Quoted 3 lines

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")
---
 drivers/fpga/dfl-fme-pr.c | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
drivers/fpga/dfl-fme-pr.c +2 -1
index cdcf6dea4cc9..96cb24787ab1 100644
@@ -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)
Signature · 1 line
2.44.0
#1 lore raw
Quoted 1 line · Peter Colberg

From: Xu Yilun <[email protected]>

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

Quoted 22 lines

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'

Quoted 3 lines
Quoted 3 lines

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")
---
 drivers/fpga/dfl-fme-pr.c | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
drivers/fpga/dfl-fme-pr.c +0 -0
index cdcf6dea4cc9..96cb24787ab1 100644

drivers/fpga/dfl-fme-pr.c static int fme_pr(struct platform_device *pdev, unsigned long arg) · line 167

Quoted 2 lines
drivers/fpga/dfl-fme-pr.c +0 -0
@@ -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?

drivers/fpga/dfl-fme-pr.c static int fme_pr(struct platform_device *pdev, unsigned long arg) · line 169

Quoted 2 lines
drivers/fpga/dfl-fme-pr.c +1 -0
  * @pdata: fme platform_device's pdata
+ * @feature: the dfl fme PR sub feature

Why adding a duplicated item would fix the warning?

drivers/fpga/dfl-fme-pr.c static void dfl_fme_destroy_bridge(struct dfl_fme_bridge *fme_br) · line 276

Quoted 8 lines
drivers/fpga/dfl-fme-pr.c +0 -1
  *
  * 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?

drivers/fpga/dfl-fme-pr.c static void dfl_fme_destroy_bridge(struct dfl_fme_bridge *fme_br) · line 277

Quoted 1 line
drivers/fpga/dfl-fme-pr.c +1 -0
+ * dfl_fme_destroy_bridges - destroy all fpga bridge platform devices

Correct the plural form in description would fix the warning?

Quoted 7 lines
drivers/fpga/dfl-fme-pr.c +0 -0
  * @pdata: fme platform device's pdata
  */
 static void dfl_fme_destroy_bridges(struct dfl_feature_platform_data *pdata)
Signature · 1 line
2.44.0
#2 lore raw
Quoted 19 lines · Xu Yilun
Quoted 1 line · Peter Colberg

From: Xu Yilun <[email protected]>

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

Quoted 13 lines

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'

Quoted 3 lines
Quoted 3 lines

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")

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

commit 782d8e61b5d6

Author: Randy Dunlap <[email protected]>
Date:   Thu Jan 12 22:37:20 2023 -0800

fpga: dfl: kernel-doc corrections

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

Quoted 42 lines

drivers/fpga/dfl-fme-pr.c static int fme_pr(struct platform_device *pdev, unsigned long arg) · line 167

Quoted 11 lines
---
 drivers/fpga/dfl-fme-pr.c | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
drivers/fpga/dfl-fme-pr.c +0 -0
index cdcf6dea4cc9..96cb24787ab1 100644
@@ -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?

drivers/fpga/dfl-fme-pr.c static int fme_pr(struct platform_device *pdev, unsigned long arg) · line 169

Quoted 2 lines
drivers/fpga/dfl-fme-pr.c +1 -0
  * @pdata: fme platform_device's pdata
+ * @feature: the dfl fme PR sub feature

Why adding a duplicated item would fix the warning?

drivers/fpga/dfl-fme-pr.c static void dfl_fme_destroy_bridge(struct dfl_fme_bridge *fme_br) · line 276

Quoted 8 lines
drivers/fpga/dfl-fme-pr.c +0 -1
  *
  * 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?

drivers/fpga/dfl-fme-pr.c static void dfl_fme_destroy_bridge(struct dfl_fme_bridge *fme_br) · line 277

Quoted 1 line
drivers/fpga/dfl-fme-pr.c +1 -0
+ * dfl_fme_destroy_bridges - destroy all fpga bridge platform devices

Correct the plural form in description would fix the warning?

Quoted 7 lines
drivers/fpga/dfl-fme-pr.c +0 -0
  * @pdata: fme platform device's pdata
  */
 static void dfl_fme_destroy_bridges(struct dfl_feature_platform_data *pdata)
Signature · 1 line
2.44.0
Signature · 1 line
#Randy
#3 lore raw
Quoted 7 lines · Randy Dunlap
Quoted 5 lines · Xu Yilun
Quoted 1 line · Peter Colberg

From: Xu Yilun <[email protected]>

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").

Quoted 18 lines
Quoted 6 lines
Quoted 6 lines

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'

Quoted 8 lines
Quoted 8 lines
Quoted 3 lines
Quoted 3 lines

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")

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

Quoted 27 lines

commit 782d8e61b5d6

Author: Randy Dunlap <[email protected]>
Date:   Thu Jan 12 22:37:20 2023 -0800

fpga: dfl: kernel-doc corrections

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

Quoted 18 lines

drivers/fpga/dfl-fme-pr.c static int fme_pr(struct platform_device *pdev, unsigned long arg) · line 167

Quoted 11 lines
---
 drivers/fpga/dfl-fme-pr.c | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
drivers/fpga/dfl-fme-pr.c +0 -0
index cdcf6dea4cc9..96cb24787ab1 100644
@@ -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?

drivers/fpga/dfl-fme-pr.c static int fme_pr(struct platform_device *pdev, unsigned long arg) · line 169

Quoted 2 lines
drivers/fpga/dfl-fme-pr.c +1 -0
  * @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

Quoted 25 lines
Quoted 24 lines

drivers/fpga/dfl-fme-pr.c static void dfl_fme_destroy_bridge(struct dfl_fme_bridge *fme_br) · line 276

Quoted 9 lines
drivers/fpga/dfl-fme-pr.c +0 -1
  *
  * 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?

drivers/fpga/dfl-fme-pr.c static void dfl_fme_destroy_bridge(struct dfl_fme_bridge *fme_br) · line 277

Quoted 1 line
drivers/fpga/dfl-fme-pr.c +1 -0
+ * dfl_fme_destroy_bridges - destroy all fpga bridge platform devices

Correct the plural form in description would fix the warning?

Quoted 7 lines
drivers/fpga/dfl-fme-pr.c +0 -0
  * @pdata: fme platform device's pdata
  */
 static void dfl_fme_destroy_bridges(struct dfl_feature_platform_data *pdata)
Signature · 1 line
2.44.0