Currently there is no automated checking for kernel-doc comments except
running 'kernel-doc -v -none <filename>'. Mention the possibility to run
kernel-doc to verify formatting of the comments in the kernel-doc guide.
Signed-off-by: Mike Rapoport <[email protected]>
---
Documentation/doc-guide/kernel-doc.rst | 6 ++++++
1 file changed, 6 insertions(+)
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index c6c3297..bb5ed6d 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -44,6 +44,12 @@ that somebody changing the code will also change the documentation. The
overview kernel-doc comments may be placed anywhere at the top indentation
level.
+Running the ``kernel-doc`` tool with increased verbosity and without actual
+output generation may be used to verify proper formating of the
+documentation comments. For example::
+
+ scripts/kernel-doc -v -none drivers/foo/bar.c
+
Function documentation
----------------------
--
2.7.4
On Tue, Feb 20, 2018 at 04:54:44PM +0200, Mike Rapoport wrote:
> level.
>
> +Running the ``kernel-doc`` tool with increased verbosity and without actual
> +output generation may be used to verify proper formating of the
"formatting"
> +documentation comments. For example::
> +
> + scripts/kernel-doc -v -none drivers/foo/bar.c
> +
> Function documentation
> ----------------------
And that's not exactly true. "make W=1" will run that exact command.
For example:
$ make W=1 net/ipv4/
(...)
CC net/ipv4/tcp_input.o
net/ipv4/tcp_input.c:4279: warning: Excess function parameter 'dest' description in 'tcp_try_coalesce'
CC net/ipv4/tcp_output.o
net/ipv4/tcp_output.c:3177: warning: Function parameter or member 'sk' not described in 'tcp_make_synack'
(...)
perhaps sneak that information in there somewhere.
Also it'll prompt people to run with W=1, so perhaps they'll fix their
more-easily-fixed warnings ;-)