[PATCH -next v1] gpio: Properly document parent data union

[PATCH -next v1] gpio: Properly document parent data union

[Joey Gouly]

Suppress a warning in the html docs by documenting these fields separately.

Signed-off-by: Joey Gouly <joey.gouly@arm.com>
Link: https://lore.kernel.org/lkml/20211027220118.71a229ab@canb.auug.org.au/
Cc: Linus Walleij <linus.walleij@linaro.org>
Cc: Bartosz Golaszewski <brgl@bgdev.pl>
Cc: Marc Zyngier <maz@kernel.org>
Cc: Stephen Rothwell <sfr@canb.auug.org.au>
---
 include/linux/gpio/driver.h | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/include/linux/gpio/driver.h b/include/linux/gpio/driver.h
index b0728c8ad90c..98c93510640e 100644
--- a/include/linux/gpio/driver.h
+++ b/include/linux/gpio/driver.h
@@ -168,13 +168,16 @@ struct gpio_irq_chip {
 
 	/**
 	 * @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:
 	 *
-	 * Data associated, and passed to, the handler for the parent
-	 * interrupt. Can either be a single pointer if @per_parent_data
-	 * is false, or an array of @num_parents pointers otherwise.  If
-	 * @per_parent_data is true, @parent_handler_data_array cannot be
-	 * NULL.
+	 * 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 {
 		void *parent_handler_data;
-- 
2.17.1

Re: [PATCH -next v1] gpio: Properly document parent data union

[Linus Walleij]

On Fri, Mar 18, 2022 at 1:12 PM Joey Gouly <joey.gouly@arm.com> wrote:

> Suppress a warning in the html docs by documenting these fields separately.
>
> Signed-off-by: Joey Gouly <joey.gouly@arm.com>
> Link: https://lore.kernel.org/lkml/20211027220118.71a229ab@canb.auug.org.au/
> Cc: Linus Walleij <linus.walleij@linaro.org>
> Cc: Bartosz Golaszewski <brgl@bgdev.pl>
> Cc: Marc Zyngier <maz@kernel.org>
> Cc: Stephen Rothwell <sfr@canb.auug.org.au>

Looks good to me!
Reviewed-by: Linus Walleij <linus.walleij@linaro.org>

Yours,
Linus Walleij

Re: [PATCH -next v1] gpio: Properly document parent data union

[Bartosz Golaszewski]

On Fri, Mar 18, 2022 at 1:12 PM Joey Gouly <joey.gouly@arm.com> wrote:
>
> Suppress a warning in the html docs by documenting these fields separately.
>
> Signed-off-by: Joey Gouly <joey.gouly@arm.com>
> Link: https://lore.kernel.org/lkml/20211027220118.71a229ab@canb.auug.org.au/
> Cc: Linus Walleij <linus.walleij@linaro.org>
> Cc: Bartosz Golaszewski <brgl@bgdev.pl>
> Cc: Marc Zyngier <maz@kernel.org>
> Cc: Stephen Rothwell <sfr@canb.auug.org.au>
> ---
>  include/linux/gpio/driver.h | 13 ++++++++-----
>  1 file changed, 8 insertions(+), 5 deletions(-)
>
> diff --git a/include/linux/gpio/driver.h b/include/linux/gpio/driver.h
> index b0728c8ad90c..98c93510640e 100644
> --- a/include/linux/gpio/driver.h
> +++ b/include/linux/gpio/driver.h
> @@ -168,13 +168,16 @@ struct gpio_irq_chip {
>
>         /**
>          * @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:
>          *
> -        * Data associated, and passed to, the handler for the parent
> -        * interrupt. Can either be a single pointer if @per_parent_data
> -        * is false, or an array of @num_parents pointers otherwise.  If
> -        * @per_parent_data is true, @parent_handler_data_array cannot be
> -        * NULL.
> +        * 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 {
>                 void *parent_handler_data;
> --
> 2.17.1
>

Applied, thanks!

Bart