Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Subject: Re: [PATCH 07/25] Documentation: gpio/driver.h: fix sphinx warnings
To:     Joe Perches <joe@perches.com>,
        "Daniel W. S. Almeida" <dwlsalmeida@gmail.com>, corbet@lwn.net,
        mchehab@kernel.org
Cc:     linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
References: <20200717185624.2009393-1-dwlsalmeida@gmail.com>
 <20200717185624.2009393-7-dwlsalmeida@gmail.com>
 <684c5c2e-1b2d-bcb4-1320-a3a0dbed9b70@infradead.org>
 <278ef62c230d69d51ca1bb4a0bbd978483f6f501.camel@perches.com>
From:   Randy Dunlap <rdunlap@infradead.org>
Message-ID: <16d8378c-ab5b-7313-3cd9-be50181330a0@infradead.org>
Date:   Fri, 17 Jul 2020 14:18:36 -0700
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101
 Thunderbird/68.9.0
MIME-Version: 1.0
In-Reply-To: <278ef62c230d69d51ca1bb4a0bbd978483f6f501.camel@perches.com>
Content-Type: text/plain; charset=utf-8
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

On 7/17/20 12:48 PM, Joe Perches wrote:
> On Fri, 2020-07-17 at 12:37 -0700, Randy Dunlap wrote:
>> On 7/17/20 11:56 AM, Daniel W. S. Almeida wrote:
>>> From: "Daniel W. S. Almeida" <dwlsalmeida@gmail.com>
>>>
>>> Fix the following warnings:
>>>
>>> warning: Function parameter or member 'gc' not described in
>>> 'gpiochip_add_data'
>>>
>>> warning: Excess function parameter 'chip' description in
>>> 'gpiochip_add_data'
>>>
>>> Signed-off-by: Daniel W. S. Almeida <dwlsalmeida@gmail.com>
>>
>> Mauro has already fixed this one.
> 
> Not quite fixed though.
> 
> Both patches did not update the text for chip->base where
> it should have been changed to gc->base
> 
> ---
>  include/linux/gpio/driver.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/include/linux/gpio/driver.h b/include/linux/gpio/driver.h
> index db82451776fc..91ae7ad8730d 100644
> --- a/include/linux/gpio/driver.h
> +++ b/include/linux/gpio/driver.h
> @@ -497,7 +497,7 @@ extern int gpiochip_add_data_with_key(struct gpio_chip *gc, void *data,
>  
>  /**
>   * gpiochip_add_data() - register a gpio_chip
> - * @gc: the chip to register, with chip->base initialized
> + * @gc: the chip to register, with gc->base initialized
>   * @data: driver-private data associated with this chip
>   *
>   * Context: potentially before irqs will work

I had a patch for this but apparently I didn't send it since
Mauro's patch had been merged. My patch is dated June 15-2020:


From: Randy Dunlap <rdunlap@infradead.org>

Fix kernel-doc warnings in <linux/gpio/driver.h>:

../include/linux/gpio/driver.h:512: warning: Function parameter or member 'gc' not described in 'gpiochip_add_data'
../include/linux/gpio/driver.h:512: warning: Excess function parameter 'chip' description in 'gpiochip_add_data'

Fixes: 959bc7b22bd2 ("gpio: Automatically add lockdep keys")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Thierry Reding <treding@nvidia.com>
Cc: Linus Walleij <linus.walleij@linaro.org>
---
MAURO!
 include/linux/gpio/driver.h |    8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

--- linux-next-20200615.orig/include/linux/gpio/driver.h
+++ linux-next-20200615/include/linux/gpio/driver.h
@@ -481,25 +481,25 @@ extern int gpiochip_add_data_with_key(st
 
 /**
  * gpiochip_add_data() - register a gpio_chip
- * @chip: the chip to register, with chip->base initialized
+ * @gc: the gpio chip to register, with gc->base initialized
  * @data: driver-private data associated with this chip
  *
  * Context: potentially before irqs will work
  *
  * When gpiochip_add_data() is called very early during boot, so that GPIOs
- * can be freely used, the chip->parent device must be registered before
+ * can be freely used, the gc->parent device must be registered before
  * the gpio framework's arch_initcall().  Otherwise sysfs initialization
  * for GPIOs will fail rudely.
  *
  * gpiochip_add_data() must only be called after gpiolib initialization,
  * ie after core_initcall().
  *
- * If chip->base is negative, this requests dynamic assignment of
+ * If gc->base is negative, this requests dynamic assignment of
  * a range of valid GPIOs.
  *
  * Returns:
  * A negative errno if the chip can't be registered, such as because the
- * chip->base is invalid or already associated with a different chip.
+ * gc->base is invalid or already associated with a different chip.
  * Otherwise it returns zero as a success code.
  */
 #ifdef CONFIG_LOCKDEP