linux-kernel - Re: [PATCH] gpio: omap: add kernel-doc comment for omap_gpio

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <20251201114602.094dce74@kemnade.info>
Date: Mon, 1 Dec 2025 11:46:02 +0100
From: Andreas Kemnade <andreas@...nade.info>
To: cjz <guagua210311@...com>
Cc: linux-gpio@...r.kernel.org, linux-omap@...r.kernel.org,
 linux-kernel@...r.kernel.org, Grygorii.Strashko@...com,
 ssantosh@...nel.org, khilman@...nel.org, linus.walleij@...aro.org,
 brgl@...nel.org
Subject: Re: [PATCH] gpio: omap: add kernel-doc comment for omap_gpio_get()

Hi,

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

> From: changjunzheng <guagua210311@...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@...1:~/linux$ touch drivers/gpio/gpio-omap.c 
andi@...1:~/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@...1:~/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