2018-02-20 18:38:05

by Mike Rapoport

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

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]>
---
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

2018-02-23 15:08:34

by Jonathan Corbet

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

On Tue, 20 Feb 2018 20:36:25 +0200
Mike Rapoport <[email protected]> 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 <[email protected]>

Applied, thanks.

jon