github-mirror/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux.git synced 2026-06-01 02:53:36 +02:00
Code Issues Actions Packages Projects Releases Wiki Activity Graph

docs: process: discourage pointless boilerplate kdoc

Browse Source 
It appears that folks "less versed in kernel coding" think that its
good style to document every function, even if they have no useful
information to pass to the future readers of the code. This used
to be just a waste of space, but with increased kdoc format linting
it's also a burden when refactoring the code.

Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Reviewed-by: Joe Damato <joe@dama.to>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250614204258.61449-1-kuba@kernel.org
This commit is contained in:
Jakub Kicinski 2025-06-14 13:42:57 -07:00 committed by Jonathan Corbet
parent 0242b8b0cc
commit e5880f95a9
1 changed files with 4 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
Documentation/process/coding-style.rst
View File

@ -614,7 +614,10 @@ it.
When commenting the kernel API functions, please use the kernel-doc format.
See the files at :ref:`Documentation/doc-guide/ <doc_guide>` and
``scripts/kernel-doc`` for details.
``scripts/kernel-doc`` for details. Note that the danger of over-commenting
applies to kernel-doc comments all the same. Do not add boilerplate
kernel-doc which simply reiterates what's obvious from the signature
of the function.
The preferred style for long (multi-line) comments is: