[PATCH] doc-guide: kernel-doc: add comment about formatting verification

[PATCH] doc-guide: kernel-doc: add comment about formatting verification

[Mike Rapoport]

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 <rppt@linux.vnet.ibm.com>
---
v2:
* fix typo
* add a sentence about using 'make W=n'

 Documentation/doc-guide/kernel-doc.rst | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index c6c3297..80383b1 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -44,6 +44,17 @@ 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 formatting of the
+documentation comments. For example::
+
+	scripts/kernel-doc -v -none drivers/foo/bar.c
+
+The documentation format is verified by the kernel build when it is
+requested to perform extra gcc checks::
+
+	make W=n
+
 Function documentation
 ----------------------
 
-- 
2.7.4

Re: [PATCH] doc-guide: kernel-doc: add comment about formatting verification

[Jonathan Corbet]

On Tue, 20 Feb 2018 20:36:25 +0200
Mike Rapoport <rppt@linux.vnet.ibm.com> wrote:

> 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 <rppt@linux.vnet.ibm.com>

Applied, thanks.

jon

Re: [PATCH] doc-guide: kernel-doc: add comment about formatting verification

[Matthew Wilcox]

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 ;-)

[PATCH] doc-guide: kernel-doc: add comment about formatting verification

[Mike Rapoport]

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 <rppt@linux.vnet.ibm.com>
---
 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