[PATCH] docs: process: discourage pointless boilerplate kdoc

[PATCH] docs: process: discourage pointless boilerplate kdoc

[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.

Signed-off-by: Jakub Kicinski <kuba@kernel.org>
---
CC: corbet@lwn.net
CC: workflows@vger.kernel.org
CC: linux-doc@vger.kernel.org
---
 Documentation/process/coding-style.rst | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 19d2ed47ff79..d1a8e5465ed9 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -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:
 
-- 
2.49.0

Re: [PATCH] docs: process: discourage pointless boilerplate kdoc

[Joe Damato]

On Sat, Jun 14, 2025 at 01:42:57PM -0700, Jakub Kicinski wrote:
> 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>
> ---
> CC: corbet@lwn.net
> CC: workflows@vger.kernel.org
> CC: linux-doc@vger.kernel.org
> ---
>  Documentation/process/coding-style.rst | 5 ++++-
>  1 file changed, 4 insertions(+), 1 deletion(-)
> 

I suppose I am guilty of this ;)

Reviewed-by: Joe Damato <joe@dama.to>

Re: [PATCH] docs: process: discourage pointless boilerplate kdoc

[Jonathan Corbet]

Jakub Kicinski <kuba@kernel.org> writes:

> 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>
> ---
> CC: corbet@lwn.net
> CC: workflows@vger.kernel.org
> CC: linux-doc@vger.kernel.org
> ---
>  Documentation/process/coding-style.rst | 5 ++++-
>  1 file changed, 4 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> index 19d2ed47ff79..d1a8e5465ed9 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -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