[PATCH] gpio: omap: add kernel-doc comment for omap_gpio_get()

[PATCH] gpio: omap: add kernel-doc comment for omap_gpio_get()

[cjz]

From: changjunzheng <guagua210311@qq.com>

omap_gpio_get() is a core function for reading OMAP GPIO pin level, but it lacks complete kernel-doc comment (no function description, parameter explanation, or return value说明). This causes gcc W=1 warning and reduces code readability.

Add standard kernel-doc comment to fix the warning and improve maintainability.

Signed-off-by: changjunzheng <guagua210311@qq.com>
---
 drivers/gpio/gpio-omap.c | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/drivers/gpio/gpio-omap.c b/drivers/gpio/gpio-omap.c
index a268c76bdca6..ad69892e9d98 100644
--- a/drivers/gpio/gpio-omap.c
+++ b/drivers/gpio/gpio-omap.c
@@ -861,6 +861,17 @@ static int omap_gpio_input(struct gpio_chip *chip, unsigned offset)
 	return 0;
 }
 
+/**
+ * omap_gpio_get - Get the logic level of an OMAP GPIO pin
+ * @chip: Pointer to the GPIO chip instance
+ * @offset: Offset of the GPIO pin within the chip's pin range
+ *
+ * Read the current logic level of the specified OMAP GPIO pin. If the pin is
+ * configured as input, read the actual pin level; if configured as output, read
+ * the last set output level.
+ *
+ * Return: 0 if the pin is at low level, 1 if at high level
+ */
 static int omap_gpio_get(struct gpio_chip *chip, unsigned offset)
 {
 	struct gpio_bank *bank = gpiochip_get_data(chip);
-- 
2.43.0

Re: [PATCH] gpio: omap: add kernel-doc comment for omap_gpio_get()

[Andreas Kemnade]

Hi,

On Mon,  1 Dec 2025 17:54:21 +0800
cjz <guagua210311@qq.com> wrote:

> From: changjunzheng <guagua210311@qq.com>
> 
> omap_gpio_get() is a core function for reading OMAP GPIO pin level, but it lacks complete kernel-doc comment (no function description, parameter explanation, or return value说明). This causes gcc W=1 warning and reduces code readability.
> 
> Add standard kernel-doc comment to fix the warning and improve maintainability.
> 
Can you elaborate on how this improves maintainability to document
obvious parameters of a local function? And why for this local function and
not for others? So why omap_gpio_runtime_suspend() which is also used
as function pointer does not need such comments?
 
Citing coding-style.rst:
"Do not add boilerplate
kernel-doc which simply reiterates what's obvious from the signature
of the function."

If that is just about compliance to some rule or make a compiler happy
in W=1, than do not disguise that and add fake arguments for your change.

BTW:  
andi@akm1:~/linux$ touch drivers/gpio/gpio-omap.c 
andi@akm1:~/linux$ make LLVM=1 ARCH=arm W=1
  CALL    scripts/checksyscalls.sh
  CC      drivers/gpio/gpio-omap.o
  AR      drivers/gpio/built-in.a
  AR      drivers/built-in.a

Silence....
with gcc again:
andi@akm1:~/linux$ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- zImage modules dtbs W=1
  CALL    scripts/checksyscalls.sh
  CC      drivers/gpio/gpio-omap.o
  AR      drivers/gpio/built-in.a
  AR      drivers/built-in.a
  AR      built-in.a
  AR      vmlinux.a
  LD      vmlinux.o

Also silence.

Regards,
Andreas