Skip to contentSkip to conversation

gpio: Fix kernel-doc comments to nested union

PATCH In review Akira Yokosawa 4 participants 5 messages Jun 6, 2022 – Jun 23, 2022

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 gpio: Fix kernel-doc comments to nested union

Commit 48ec13d36d3f ("gpio: Properly document parent data union") is supposed to have fixed a warning from "make htmldocs" regarding kernel-doc comments to union members. However, the same warning still remains [1].

Fix the issue by following the example found in section "Nested structs/unions" of Documentation/doc-guide/kernel-doc.rst.

Fixes 48ec13d36d3f ("gpio: Properly document parent data union")
Cc Linus Walleij <[email protected]>
Cc Bartosz Golaszewski <[email protected]>
Cc Joey Gouly <[email protected]>
Cc Marc Zyngier <[email protected]>
---
 include/linux/gpio/driver.h | 29 ++++++++++++++++-------------
 1 file changed, 16 insertions(+), 13 deletions(-)
include/linux/gpio/driver.h +16 -13
index b1e0f1f8ee2e..54c3c6506503 100644
@@ -167,21 +167,24 @@ struct gpio_irq_chip {
 	 */
 	irq_flow_handler_t parent_handler;
 
-	/**
-	 * @parent_handler_data:
-	 *
-	 * If @per_parent_data is false, @parent_handler_data is a single
-	 * pointer used as the data associated with every parent interrupt.
-	 *
-	 * @parent_handler_data_array:
-	 *
-	 * If @per_parent_data is true, @parent_handler_data_array is
-	 * an array of @num_parents pointers, and is used to associate
-	 * different data for each parent. This cannot be NULL if
-	 * @per_parent_data is true.
-	 */
 	union {
+		/**
+		 * @parent_handler_data:
+		 *
+		 * If @per_parent_data is false, @parent_handler_data is a
+		 * single pointer used as the data associated with every
+		 * parent interrupt.
+		 */
 		void *parent_handler_data;
+
+		/**
+		 * @parent_handler_data_array:
+		 *
+		 * If @per_parent_data is true, @parent_handler_data_array is
+		 * an array of @num_parents pointers, and is used to associate
+		 * different data for each parent. This cannot be NULL if
+		 * @per_parent_data is true.
+		 */
 		void **parent_handler_data_array;
 	};
 

base-commit: f2906aa863381afb0015a9eb7fefad885d4e5a56

Signature · 1 line
2.25.1
Tested-by on v1 1/1
#1 lore raw

Hi Akira,

Quoted 17 lines · On Mon, 6 Jun 2022 13:44:24 +0900 Akira Yokosawa <[email protected]> wrote:

Commit 48ec13d36d3f ("gpio: Properly document parent data union") is supposed to have fixed a warning from "make htmldocs" regarding kernel-doc comments to union members. However, the same warning still remains [1].

Fix the issue by following the example found in section "Nested structs/unions" of Documentation/doc-guide/kernel-doc.rst.

Fixes 48ec13d36d3f ("gpio: Properly document parent data union")
Cc Linus Walleij <[email protected]>
Cc Bartosz Golaszewski <[email protected]>
Cc Joey Gouly <[email protected]>
Cc Marc Zyngier <[email protected]>
Quoted 3 lines
---
 include/linux/gpio/driver.h | 29 ++++++++++++++++-------------
 1 file changed, 16 insertions(+), 13 deletions(-)

Looks good, thanks.

Signature · 2 lines
Cheers,
Stephen Rothwell
Reviewed-by on v1 1/1
#2 lore raw
In reply to Akira Yokosawa

Em Mon, 6 Jun 2022 13:44:24 +0900
Akira Yokosawa <[email protected]> escreveu:

Quoted 51 lines

Commit 48ec13d36d3f ("gpio: Properly document parent data union") is supposed to have fixed a warning from "make htmldocs" regarding kernel-doc comments to union members. However, the same warning still remains [1].

Fix the issue by following the example found in section "Nested structs/unions" of Documentation/doc-guide/kernel-doc.rst.

Fixes 48ec13d36d3f ("gpio: Properly document parent data union")
Cc Linus Walleij <[email protected]>
Cc Bartosz Golaszewski <[email protected]>
Cc Joey Gouly <[email protected]>
Cc Marc Zyngier <[email protected]>
---
 include/linux/gpio/driver.h | 29 ++++++++++++++++-------------
 1 file changed, 16 insertions(+), 13 deletions(-)
include/linux/gpio/driver.h +8 -13
index b1e0f1f8ee2e..54c3c6506503 100644
@@ -167,21 +167,24 @@ struct gpio_irq_chip {
 	 */
 	irq_flow_handler_t parent_handler;
 
-	/**
-	 * @parent_handler_data:
-	 *
-	 * If @per_parent_data is false, @parent_handler_data is a single
-	 * pointer used as the data associated with every parent interrupt.
-	 *
-	 * @parent_handler_data_array:
-	 *
-	 * If @per_parent_data is true, @parent_handler_data_array is
-	 * an array of @num_parents pointers, and is used to associate
-	 * different data for each parent. This cannot be NULL if
-	 * @per_parent_data is true.
-	 */
 	union {
+		/**
+		 * @parent_handler_data:
+		 *
+		 * If @per_parent_data is false, @parent_handler_data is a
+		 * single pointer used as the data associated with every
+		 * parent interrupt.
+		 */
 		void *parent_handler_data;
+

include/linux/gpio/driver.h struct gpio_irq_chip { · line 189

Quoted 10 lines
include/linux/gpio/driver.h +8 -0
+		/**
+		 * @parent_handler_data_array:
+		 *
+		 * If @per_parent_data is true, @parent_handler_data_array is
+		 * an array of @num_parents pointers, and is used to associate
+		 * different data for each parent. This cannot be NULL if
+		 * @per_parent_data is true.
+		 */
 		void **parent_handler_data_array;
 	};

Yeah, kernel-doc expects inlined comments to be just before each declaration like the above.

Regards,
Mauro

#3 lore raw
In reply to Akira Yokosawa
Quoted 8 lines · Akira Yokosawa

Commit 48ec13d36d3f ("gpio: Properly document parent data union") is supposed to have fixed a warning from "make htmldocs" regarding kernel-doc comments to union members. However, the same warning still remains [1].

Fix the issue by following the example found in section "Nested structs/unions" of Documentation/doc-guide/kernel-doc.rst.

Quoted 8 lines
Fixes 48ec13d36d3f ("gpio: Properly document parent data union")
Cc Linus Walleij <[email protected]>
Cc Bartosz Golaszewski <[email protected]>
Cc Joey Gouly <[email protected]>
Cc Marc Zyngier <[email protected]>

Gentle ping to gpio maintainers.

I thought this fix would go through brgl's tree.

Thanks, Akira

Quoted 48 lines
---
 include/linux/gpio/driver.h | 29 ++++++++++++++++-------------
 1 file changed, 16 insertions(+), 13 deletions(-)
include/linux/gpio/driver.h +16 -13
index b1e0f1f8ee2e..54c3c6506503 100644
@@ -167,21 +167,24 @@ struct gpio_irq_chip {
 	 */
 	irq_flow_handler_t parent_handler;
 
-	/**
-	 * @parent_handler_data:
-	 *
-	 * If @per_parent_data is false, @parent_handler_data is a single
-	 * pointer used as the data associated with every parent interrupt.
-	 *
-	 * @parent_handler_data_array:
-	 *
-	 * If @per_parent_data is true, @parent_handler_data_array is
-	 * an array of @num_parents pointers, and is used to associate
-	 * different data for each parent. This cannot be NULL if
-	 * @per_parent_data is true.
-	 */
 	union {
+		/**
+		 * @parent_handler_data:
+		 *
+		 * If @per_parent_data is false, @parent_handler_data is a
+		 * single pointer used as the data associated with every
+		 * parent interrupt.
+		 */
 		void *parent_handler_data;
+
+		/**
+		 * @parent_handler_data_array:
+		 *
+		 * If @per_parent_data is true, @parent_handler_data_array is
+		 * an array of @num_parents pointers, and is used to associate
+		 * different data for each parent. This cannot be NULL if
+		 * @per_parent_data is true.
+		 */
 		void **parent_handler_data_array;
 	};
 

base-commit: f2906aa863381afb0015a9eb7fefad885d4e5a56

#4 lore raw
Quoted 18 lines · Akira Yokosawa
Quoted 8 lines · Akira Yokosawa

Commit 48ec13d36d3f ("gpio: Properly document parent data union") is supposed to have fixed a warning from "make htmldocs" regarding kernel-doc comments to union members. However, the same warning still remains [1].

Fix the issue by following the example found in section "Nested structs/unions" of Documentation/doc-guide/kernel-doc.rst.

Quoted 8 lines
Fixes 48ec13d36d3f ("gpio: Properly document parent data union")
Cc Linus Walleij <[email protected]>
Cc Bartosz Golaszewski <[email protected]>
Cc Joey Gouly <[email protected]>
Cc Marc Zyngier <[email protected]>
Quoted 6 lines

Gentle ping to gpio maintainers.

I thought this fix would go through brgl's tree.

Thanks, Akira

Now applied, thanks! Sorry for the delay.

Bart