Skip to contentSkip to conversation

fpga: fix kernel-doc warnings and align descriptions for the core components

RFC PATCH Applied Marco Pagani 3 participants 9 messages Jul 6, 2023 – Jul 10, 2023 FPGA manager framework

lore
Share & tools
lore
#0 lore raw

cover fpga: fix kernel-doc warnings and align descriptions for the core components

This patch set fixes all kernel-doc warnings reported by the kernel-doc script for the core components of the subsystem and aligns descriptions with current implementations

Marco Pagani (2):
fpga: region: fix kernel-doc
fpga: bridge: fix kernel-doc

 drivers/fpga/fpga-bridge.c | 23 ++++++++++++-----------
 drivers/fpga/fpga-region.c | 14 ++++++++------
 2 files changed, 20 insertions(+), 17 deletions(-)

base-commit: 45a3e24f65e90a047bef86f927ebdc4c710edaa1

Signature · 1 line
2.41.0
#1 lore raw

RFC PATCH 1/2 fpga: region: fix kernel-doc

- Fix the following warnings issued by the kernel-doc script:

drivers/fpga/fpga-region.c:46: warning: No description found for return value of 'fpga_region_get' drivers/fpga/fpga-region.c:97: warning: No description found for return value of 'fpga_region_program_fpga' drivers/fpga/fpga-region.c:295: warning: No description found for return value of 'fpga_region_init'

- Remove the "and registers a reconfig notifier" part from the description of fpga_region_init() since it does not register an of_overlay notifier anymore.

- Remove the outdated "if @np is not an FPGA Region" case from the return description of fpga_region_get() and replace it with the case when try_module_get() fails.

---
 drivers/fpga/fpga-region.c | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)
drivers/fpga/fpga-region.c +8 -6
index ccf6fdab1360..c9d065a6961b 100644
@@ -38,9 +38,10 @@ EXPORT_SYMBOL_GPL(fpga_region_class_find);
  *
  * Caller should call fpga_region_put() when done with region.
  *
- * Return fpga_region struct if successful.
- * Return -EBUSY if someone already has a reference to the region.
- * Return -ENODEV if @np is not an FPGA Region.
+ * Return:
+ * * fpga_region struct if successful.
+ * * -EBUSY if someone already has a reference to the region.
+ * * -ENODEV if can't take parent driver module refcount.
  */
 static struct fpga_region *fpga_region_get(struct fpga_region *region)
 {
@@ -91,7 +92,7 @@ static void fpga_region_put(struct fpga_region *region)
  * The caller will need to call fpga_bridges_put() before attempting to
  * reprogram the region.
  *
- * Return 0 for success or negative error code.
+ * Return: 0 for success or negative error code.
  */
 int fpga_region_program_fpga(struct fpga_region *region)
 {
@@ -288,8 +289,9 @@ static void fpga_region_dev_release(struct device *dev)
 }
 
 /**
- * fpga_region_init - init function for fpga_region class
- * Creates the fpga_region class and registers a reconfig notifier.
+ * fpga_region_init - creates the fpga_region class.
+ *
+ * Return: 0 on success or ERR_PTR() on error.
  */
 static int __init fpga_region_init(void)
 {
Signature · 1 line
2.41.0
Reviewed-by on v1 1/2
#2 lore raw

Re: [RFC PATCH 1/2] fpga: region: fix kernel-doc

Hi--

Quoted 10 lines · Marco Pagani

- Fix the following warnings issued by the kernel-doc script:

drivers/fpga/fpga-region.c:46: warning: No description found for return value of 'fpga_region_get' drivers/fpga/fpga-region.c:97: warning: No description found for return value of 'fpga_region_program_fpga' drivers/fpga/fpga-region.c:295: warning: No description found for return value of 'fpga_region_init'

- Remove the "and registers a reconfig notifier" part from the description of fpga_region_init() since it does not register an of_overlay notifier anymore.

Quoted 5 lines

- Remove the outdated "if @np is not an FPGA Region" case from the return description of fpga_region_get() and replace it with the case when try_module_get() fails.

Looks good. Thanks.

Quoted 43 lines
---
 drivers/fpga/fpga-region.c | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)
drivers/fpga/fpga-region.c +8 -6
index ccf6fdab1360..c9d065a6961b 100644
@@ -38,9 +38,10 @@ EXPORT_SYMBOL_GPL(fpga_region_class_find);
  *
  * Caller should call fpga_region_put() when done with region.
  *
- * Return fpga_region struct if successful.
- * Return -EBUSY if someone already has a reference to the region.
- * Return -ENODEV if @np is not an FPGA Region.
+ * Return:
+ * * fpga_region struct if successful.
+ * * -EBUSY if someone already has a reference to the region.
+ * * -ENODEV if can't take parent driver module refcount.
  */
 static struct fpga_region *fpga_region_get(struct fpga_region *region)
 {
@@ -91,7 +92,7 @@ static void fpga_region_put(struct fpga_region *region)
  * The caller will need to call fpga_bridges_put() before attempting to
  * reprogram the region.
  *
- * Return 0 for success or negative error code.
+ * Return: 0 for success or negative error code.
  */
 int fpga_region_program_fpga(struct fpga_region *region)
 {
@@ -288,8 +289,9 @@ static void fpga_region_dev_release(struct device *dev)
 }
 
 /**
- * fpga_region_init - init function for fpga_region class
- * Creates the fpga_region class and registers a reconfig notifier.
+ * fpga_region_init - creates the fpga_region class.
+ *
+ * Return: 0 on success or ERR_PTR() on error.
  */
 static int __init fpga_region_init(void)
 {
Signature · 1 line
~Randy
maintainer Acked-by Applied
#3 lore raw

Re: [RFC PATCH 1/2] fpga: region: fix kernel-doc

Quoted 17 lines · Randy Dunlap

Hi--

Quoted 14 lines · Marco Pagani

- Fix the following warnings issued by the kernel-doc script:

drivers/fpga/fpga-region.c:46: warning: No description found for return value of 'fpga_region_get' drivers/fpga/fpga-region.c:97: warning: No description found for return value of 'fpga_region_program_fpga' drivers/fpga/fpga-region.c:295: warning: No description found for return value of 'fpga_region_init'

- Remove the "and registers a reconfig notifier" part from the description of fpga_region_init() since it does not register an of_overlay notifier anymore.

- Remove the outdated "if @np is not an FPGA Region" case from the return description of fpga_region_get() and replace it with the case when try_module_get() fails.

Quoted 5 lines
Quoted 1 line

Looks good. Thanks.

Applied.

BTW: No need to have RFC if you think it is ready for full review.

#4 lore raw

RFC PATCH 2/2 fpga: bridge: fix kernel-doc

In reply to Marco Pagani

Fix the following warnings issued by the kernel-doc script:

drivers/fpga/fpga-bridge.c:99: warning: No description found for return value of 'of_fpga_bridge_get' drivers/fpga/fpga-bridge.c:163: warning: No description found for return value of 'fpga_bridges_enable' drivers/fpga/fpga-bridge.c:187: warning: No description found for return value of 'fpga_bridges_disable' drivers/fpga/fpga-bridge.c:238: warning: No description found for return value of 'of_fpga_bridge_get_to_list' drivers/fpga/fpga-bridge.c:268: warning: No description found for return value of 'fpga_bridge_get_to_list'

- Extend the return description of of_fpga_bridge_get() to include the case when try_module_get() fails.

---
 drivers/fpga/fpga-bridge.c | 23 ++++++++++++-----------
 1 file changed, 12 insertions(+), 11 deletions(-)
drivers/fpga/fpga-bridge.c +12 -11
index a6c25dee9cc1..0b76c67c50e5 100644
@@ -87,12 +87,13 @@ static struct fpga_bridge *__fpga_bridge_get(struct device *dev,
 /**
  * of_fpga_bridge_get - get an exclusive reference to an fpga bridge
  *
- * @np: node pointer of an FPGA bridge
- * @info: fpga image specific information
+ * @np: node pointer of an FPGA bridge.
+ * @info: fpga image specific information.
  *
- * Return fpga_bridge struct if successful.
- * Return -EBUSY if someone already has a reference to the bridge.
- * Return -ENODEV if @np is not an FPGA Bridge.
+ * Return:
+ * * fpga_bridge struct pointer if successful.
+ * * -EBUSY if someone already has a reference to the bridge.
+ * * -ENODEV if @np is not an FPGA Bridge or can't take parent driver refcount.
  */
 struct fpga_bridge *of_fpga_bridge_get(struct device_node *np,
 				       struct fpga_image_info *info)
@@ -155,9 +156,9 @@ EXPORT_SYMBOL_GPL(fpga_bridge_put);
  * fpga_bridges_enable - enable bridges in a list
  * @bridge_list: list of FPGA bridges
  *
- * Enable each bridge in the list.  If list is empty, do nothing.
+ * Enable each bridge in the list. If list is empty, do nothing.
  *
- * Return 0 for success or empty bridge list; return error code otherwise.
+ * Return: 0 for success or empty bridge list or an error code otherwise.
  */
 int fpga_bridges_enable(struct list_head *bridge_list)
 {
@@ -179,9 +180,9 @@ EXPORT_SYMBOL_GPL(fpga_bridges_enable);
  *
  * @bridge_list: list of FPGA bridges
  *
- * Disable each bridge in the list.  If list is empty, do nothing.
+ * Disable each bridge in the list. If list is empty, do nothing.
  *
- * Return 0 for success or empty bridge list; return error code otherwise.
+ * Return: 0 for success or empty bridge list or an error code otherwise.
  */
 int fpga_bridges_disable(struct list_head *bridge_list)
 {
@@ -230,7 +231,7 @@ EXPORT_SYMBOL_GPL(fpga_bridges_put);
  *
  * Get an exclusive reference to the bridge and it to the list.
  *
- * Return 0 for success, error code from of_fpga_bridge_get() otherwise.
+ * Return: 0 for success, error code from of_fpga_bridge_get() otherwise.
  */
 int of_fpga_bridge_get_to_list(struct device_node *np,
 			       struct fpga_image_info *info,
@@ -260,7 +261,7 @@ EXPORT_SYMBOL_GPL(of_fpga_bridge_get_to_list);
  *
  * Get an exclusive reference to the bridge and it to the list.
  *
- * Return 0 for success, error code from fpga_bridge_get() otherwise.
+ * Return: 0 for success, error code from fpga_bridge_get() otherwise.
  */
 int fpga_bridge_get_to_list(struct device *dev,
 			    struct fpga_image_info *info,
Signature · 1 line
2.41.0
Reviewed-by on v1 2/2
#5 lore raw

Re: [RFC PATCH 2/2] fpga: bridge: fix kernel-doc

HI--

Quoted 21 lines · Marco Pagani

Fix the following warnings issued by the kernel-doc script:

drivers/fpga/fpga-bridge.c:99: warning: No description found for return value of 'of_fpga_bridge_get' drivers/fpga/fpga-bridge.c:163: warning: No description found for return value of 'fpga_bridges_enable' drivers/fpga/fpga-bridge.c:187: warning: No description found for return value of 'fpga_bridges_disable' drivers/fpga/fpga-bridge.c:238: warning: No description found for return value of 'of_fpga_bridge_get_to_list' drivers/fpga/fpga-bridge.c:268: warning: No description found for return value of 'fpga_bridge_get_to_list'

- Extend the return description of of_fpga_bridge_get() to include the case when try_module_get() fails.

---
 drivers/fpga/fpga-bridge.c | 23 ++++++++++++-----------
 1 file changed, 12 insertions(+), 11 deletions(-)
drivers/fpga/fpga-bridge.c +0 -0
index a6c25dee9cc1..0b76c67c50e5 100644

drivers/fpga/fpga-bridge.c static struct fpga_bridge *__fpga_bridge_get(struct device *dev, · line 91

Quoted 7 lines
drivers/fpga/fpga-bridge.c +2 -2
@@ -87,12 +87,13 @@ static struct fpga_bridge *__fpga_bridge_get(struct device *dev,
 /**
  * of_fpga_bridge_get - get an exclusive reference to an fpga bridge
  *
- * @np: node pointer of an FPGA bridge
- * @info: fpga image specific information
+ * @np: node pointer of an FPGA bridge.
+ * @info: fpga image specific information.

Those are not sentences. There is no reason that a period ('.') is needed to end those lines. OTOH, the maintainers can do as they like with it.

The rest looks good. Thanks.

Quoted 53 lines
drivers/fpga/fpga-bridge.c +10 -9
  *
- * Return fpga_bridge struct if successful.
- * Return -EBUSY if someone already has a reference to the bridge.
- * Return -ENODEV if @np is not an FPGA Bridge.
+ * Return:
+ * * fpga_bridge struct pointer if successful.
+ * * -EBUSY if someone already has a reference to the bridge.
+ * * -ENODEV if @np is not an FPGA Bridge or can't take parent driver refcount.
  */
 struct fpga_bridge *of_fpga_bridge_get(struct device_node *np,
 				       struct fpga_image_info *info)
@@ -155,9 +156,9 @@ EXPORT_SYMBOL_GPL(fpga_bridge_put);
  * fpga_bridges_enable - enable bridges in a list
  * @bridge_list: list of FPGA bridges
  *
- * Enable each bridge in the list.  If list is empty, do nothing.
+ * Enable each bridge in the list. If list is empty, do nothing.
  *
- * Return 0 for success or empty bridge list; return error code otherwise.
+ * Return: 0 for success or empty bridge list or an error code otherwise.
  */
 int fpga_bridges_enable(struct list_head *bridge_list)
 {
@@ -179,9 +180,9 @@ EXPORT_SYMBOL_GPL(fpga_bridges_enable);
  *
  * @bridge_list: list of FPGA bridges
  *
- * Disable each bridge in the list.  If list is empty, do nothing.
+ * Disable each bridge in the list. If list is empty, do nothing.
  *
- * Return 0 for success or empty bridge list; return error code otherwise.
+ * Return: 0 for success or empty bridge list or an error code otherwise.
  */
 int fpga_bridges_disable(struct list_head *bridge_list)
 {
@@ -230,7 +231,7 @@ EXPORT_SYMBOL_GPL(fpga_bridges_put);
  *
  * Get an exclusive reference to the bridge and it to the list.
  *
- * Return 0 for success, error code from of_fpga_bridge_get() otherwise.
+ * Return: 0 for success, error code from of_fpga_bridge_get() otherwise.
  */
 int of_fpga_bridge_get_to_list(struct device_node *np,
 			       struct fpga_image_info *info,
@@ -260,7 +261,7 @@ EXPORT_SYMBOL_GPL(of_fpga_bridge_get_to_list);
  *
  * Get an exclusive reference to the bridge and it to the list.
  *
- * Return 0 for success, error code from fpga_bridge_get() otherwise.
+ * Return: 0 for success, error code from fpga_bridge_get() otherwise.
  */
 int fpga_bridge_get_to_list(struct device *dev,
 			    struct fpga_image_info *info,
Signature · 1 line
~Randy
#6 lore raw

Re: [RFC PATCH 2/2] fpga: bridge: fix kernel-doc

Hi again,

Quoted 48 lines · Randy Dunlap

HI--

Quoted 21 lines · Marco Pagani

Fix the following warnings issued by the kernel-doc script:

drivers/fpga/fpga-bridge.c:99: warning: No description found for return value of 'of_fpga_bridge_get' drivers/fpga/fpga-bridge.c:163: warning: No description found for return value of 'fpga_bridges_enable' drivers/fpga/fpga-bridge.c:187: warning: No description found for return value of 'fpga_bridges_disable' drivers/fpga/fpga-bridge.c:238: warning: No description found for return value of 'of_fpga_bridge_get_to_list' drivers/fpga/fpga-bridge.c:268: warning: No description found for return value of 'fpga_bridge_get_to_list'

- Extend the return description of of_fpga_bridge_get() to include the case when try_module_get() fails.

---
 drivers/fpga/fpga-bridge.c | 23 ++++++++++++-----------
 1 file changed, 12 insertions(+), 11 deletions(-)
drivers/fpga/fpga-bridge.c +0 -0
index a6c25dee9cc1..0b76c67c50e5 100644

drivers/fpga/fpga-bridge.c static struct fpga_bridge *__fpga_bridge_get(struct device *dev, · line 91

Quoted 7 lines
drivers/fpga/fpga-bridge.c +2 -2
@@ -87,12 +87,13 @@ static struct fpga_bridge *__fpga_bridge_get(struct device *dev,
 /**
  * of_fpga_bridge_get - get an exclusive reference to an fpga bridge
  *
- * @np: node pointer of an FPGA bridge
- * @info: fpga image specific information
+ * @np: node pointer of an FPGA bridge.
+ * @info: fpga image specific information.

Those are not sentences. There is no reason that a period ('.') is needed to end those lines. OTOH, the maintainers can do as they like with it.

The rest looks good. Thanks.

Quoted 9 lines
drivers/fpga/fpga-bridge.c +4 -3
  *
- * Return fpga_bridge struct if successful.
- * Return -EBUSY if someone already has a reference to the bridge.
- * Return -ENODEV if @np is not an FPGA Bridge.
+ * Return:
+ * * fpga_bridge struct pointer if successful.
+ * * -EBUSY if someone already has a reference to the bridge.
+ * * -ENODEV if @np is not an FPGA Bridge or can't take parent driver refcount.
  */
Quoted 8 lines

drivers/fpga/fpga-bridge.c EXPORT_SYMBOL_GPL(fpga_bridge_put); · line 159

Quoted 8 lines
drivers/fpga/fpga-bridge.c +1 -1
 struct fpga_bridge *of_fpga_bridge_get(struct device_node *np,
 				       struct fpga_image_info *info)
@@ -155,9 +156,9 @@ EXPORT_SYMBOL_GPL(fpga_bridge_put);
  * fpga_bridges_enable - enable bridges in a list
  * @bridge_list: list of FPGA bridges
  *
- * Enable each bridge in the list.  If list is empty, do nothing.
+ * Enable each bridge in the list. If list is empty, do nothing.

These (multiple) 2-space to 1-space changes also are not necessary but are at the discretion of the maintainers.

Quoted 37 lines
Quoted 36 lines
drivers/fpga/fpga-bridge.c +5 -5
  *
- * Return 0 for success or empty bridge list; return error code otherwise.
+ * Return: 0 for success or empty bridge list or an error code otherwise.
  */
 int fpga_bridges_enable(struct list_head *bridge_list)
 {
@@ -179,9 +180,9 @@ EXPORT_SYMBOL_GPL(fpga_bridges_enable);
  *
  * @bridge_list: list of FPGA bridges
  *
- * Disable each bridge in the list.  If list is empty, do nothing.
+ * Disable each bridge in the list. If list is empty, do nothing.
  *
- * Return 0 for success or empty bridge list; return error code otherwise.
+ * Return: 0 for success or empty bridge list or an error code otherwise.
  */
 int fpga_bridges_disable(struct list_head *bridge_list)
 {
@@ -230,7 +231,7 @@ EXPORT_SYMBOL_GPL(fpga_bridges_put);
  *
  * Get an exclusive reference to the bridge and it to the list.
  *
- * Return 0 for success, error code from of_fpga_bridge_get() otherwise.
+ * Return: 0 for success, error code from of_fpga_bridge_get() otherwise.
  */
 int of_fpga_bridge_get_to_list(struct device_node *np,
 			       struct fpga_image_info *info,
@@ -260,7 +261,7 @@ EXPORT_SYMBOL_GPL(of_fpga_bridge_get_to_list);
  *
  * Get an exclusive reference to the bridge and it to the list.
  *
- * Return 0 for success, error code from fpga_bridge_get() otherwise.
+ * Return: 0 for success, error code from fpga_bridge_get() otherwise.
  */
 int fpga_bridge_get_to_list(struct device *dev,
 			    struct fpga_image_info *info,
Signature · 1 line
~Randy
#7 lore raw

Re: [RFC PATCH 2/2] fpga: bridge: fix kernel-doc

In reply to Randy Dunlap
Quoted 35 lines · Randy Dunlap

HI--

Quoted 21 lines · Marco Pagani

Fix the following warnings issued by the kernel-doc script:

drivers/fpga/fpga-bridge.c:99: warning: No description found for return value of 'of_fpga_bridge_get' drivers/fpga/fpga-bridge.c:163: warning: No description found for return value of 'fpga_bridges_enable' drivers/fpga/fpga-bridge.c:187: warning: No description found for return value of 'fpga_bridges_disable' drivers/fpga/fpga-bridge.c:238: warning: No description found for return value of 'of_fpga_bridge_get_to_list' drivers/fpga/fpga-bridge.c:268: warning: No description found for return value of 'fpga_bridge_get_to_list'

- Extend the return description of of_fpga_bridge_get() to include the case when try_module_get() fails.

---
 drivers/fpga/fpga-bridge.c | 23 ++++++++++++-----------
 1 file changed, 12 insertions(+), 11 deletions(-)
drivers/fpga/fpga-bridge.c +0 -0
index a6c25dee9cc1..0b76c67c50e5 100644

drivers/fpga/fpga-bridge.c static struct fpga_bridge *__fpga_bridge_get(struct device *dev, · line 91

Quoted 7 lines
drivers/fpga/fpga-bridge.c +2 -2
@@ -87,12 +87,13 @@ static struct fpga_bridge *__fpga_bridge_get(struct device *dev,
 /**
  * of_fpga_bridge_get - get an exclusive reference to an fpga bridge
  *
- * @np: node pointer of an FPGA bridge
- * @info: fpga image specific information
+ * @np: node pointer of an FPGA bridge.
+ * @info: fpga image specific information.

Those are not sentences. There is no reason that a period ('.') is needed to end those lines. OTOH, the maintainers can do as they like with it.

Quoted 3 lines

The rest looks good. Thanks.

I added a period at the end of each argument description to follow the style recommended in the "Function documentation" section of the kernel-doc documentation.

Thanks,
Marco

[...]

maintainer Acked-by Applied
#8 lore raw

Re: [RFC PATCH 2/2] fpga: bridge: fix kernel-doc

Quoted 38 lines · Marco Pagani
Quoted 35 lines · Randy Dunlap

HI--

Quoted 21 lines · Marco Pagani

Fix the following warnings issued by the kernel-doc script:

drivers/fpga/fpga-bridge.c:99: warning: No description found for return value of 'of_fpga_bridge_get' drivers/fpga/fpga-bridge.c:163: warning: No description found for return value of 'fpga_bridges_enable' drivers/fpga/fpga-bridge.c:187: warning: No description found for return value of 'fpga_bridges_disable' drivers/fpga/fpga-bridge.c:238: warning: No description found for return value of 'of_fpga_bridge_get_to_list' drivers/fpga/fpga-bridge.c:268: warning: No description found for return value of 'fpga_bridge_get_to_list'

- Extend the return description of of_fpga_bridge_get() to include the case when try_module_get() fails.

---
 drivers/fpga/fpga-bridge.c | 23 ++++++++++++-----------
 1 file changed, 12 insertions(+), 11 deletions(-)
drivers/fpga/fpga-bridge.c +0 -0
index a6c25dee9cc1..0b76c67c50e5 100644

drivers/fpga/fpga-bridge.c static struct fpga_bridge *__fpga_bridge_get(struct device *dev, · line 91

Quoted 7 lines
drivers/fpga/fpga-bridge.c +2 -2
@@ -87,12 +87,13 @@ static struct fpga_bridge *__fpga_bridge_get(struct device *dev,
 /**
  * of_fpga_bridge_get - get an exclusive reference to an fpga bridge
  *
- * @np: node pointer of an FPGA bridge
- * @info: fpga image specific information
+ * @np: node pointer of an FPGA bridge.
+ * @info: fpga image specific information.

Those are not sentences. There is no reason that a period ('.') is needed to end those lines. OTOH, the maintainers can do as they like with it.

Quoted 7 lines
Quoted 3 lines

The rest looks good. Thanks.

I added a period at the end of each argument description to follow the style recommended in the "Function documentation" section of the kernel-doc documentation.

I'm OK with them.

Applied.

Quoted 6 lines

Thanks,
Marco

[...]