Skip to contentSkip to conversation

docs: process: discourage pointless boilerplate kdoc

PATCH Applied Jakub Kicinski 3 participants 3 messages Jun 14, 2025 – Jun 21, 2025

Subsystems (4)
lore
Share & tools
lore

Jakub Kicinski

author maintainer
#0 lore raw

PATCH 1/1 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.

---
CC: [email protected]
CC: [email protected]
CC: [email protected]

---
 Documentation/process/coding-style.rst | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)
Documentation/process/coding-style.rst +4 -1
index 19d2ed47ff79..d1a8e5465ed9 100644
@@ -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:
 
Signature · 1 line
2.49.0
Reviewed-by on v1 1/1
#1 lore raw
Quoted 6 lines · Jakub Kicinski

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.

Quoted 9 lines

---
CC: [email protected]
CC: [email protected]
CC: [email protected]

---
 Documentation/process/coding-style.rst | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

I suppose I am guilty of this ;)

maintainer Applied
#2 lore raw
In reply to Jakub Kicinski
Quoted 20 lines · Jakub Kicinski

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.

---
CC: [email protected]
CC: [email protected]
CC: [email protected]

---
 Documentation/process/coding-style.rst | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)
Documentation/process/coding-style.rst +0 -0
index 19d2ed47ff79..d1a8e5465ed9 100644

Documentation/process/coding-style.rst it. · line 620

Quoted 8 lines
Documentation/process/coding-style.rst +4 -1
@@ -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.

Applied, thanks.

jon