Commit e5880f95 authored by Jakub Kicinski's avatar Jakub Kicinski Committed by Jonathan Corbet
Browse files

docs: process: discourage pointless boilerplate kdoc 



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: default avatarJakub Kicinski <kuba@kernel.org>
Reviewed-by: default avatarJoe Damato <joe@dama.to>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250614204258.61449-1-kuba@kernel.org
parent 0242b8b0

Documentation/process/coding-style.rst

+4 −1
Original line number Diff line number Diff line
@@ -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: