Re: [PATCH] include/hw/qdev-core.h: Correct and clarify gpio doc comments

[Philippe Mathieu-Daudé]

On 8/7/24 17:33, Peter Maydell wrote:
> The doc comments for the functions for named GPIO inputs and
> outputs had a couple of problems:
>   * some copy-and-paste errors meant the qdev_connect_gpio_out_named()
>     doc comment had references to input GPIOs that should be to
>     output GPIOs
>   * it wasn't very clear that named GPIOs are arrays and so the
>     connect functions specify a single GPIO line by giving both
>     the name of the array and the index within that array
>
> Fix the copy-and-paste errors and slightly expand the text
> to say that functions are connecting one line in a named GPIO
> array, not a single named GPIO line.
>
> Reported-by: BALATON Zoltan <balaton@eik.bme.hu>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
> Does this help? I wrote the text and know what the functions do
> to start with so it's a bit tricky for me to see where the docs
> don't state things as clearly as they ought to do...
> ---
>   include/hw/qdev-core.h | 17 +++++++++--------
>   1 file changed, 9 insertions(+), 8 deletions(-)


> - * This function connects an anonymous output GPIO line on a device
> - * up to an arbitrary qemu_irq, so that when the device asserts that
> - * output GPIO line, the qemu_irq's callback is invoked.
> + * This function connects a single GPIO output in a named array of output
> + * GPIO lines on a device up to an arbitrary qemu_irq, so that when the
> + * device asserts that output GPIO line, the qemu_irq's callback is invoked.
>    * The @name string must correspond to an output GPIO array which exists on
>    * the device, and the index @n of the GPIO line must be valid (i.e.
> - * be at least 0 and less than the total number of input GPIOs in that
> + * be at least 0 and less than the total number of output GPIOs in that

Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>

And queued, thanks!