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

[Andreas Kemnade <andreas@kemnade.info>]

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