The documentation states that:
make W=n
can be used to verify the documentation format. This is true for .c
files but not for headers [1].
Modify the documentation to specify that headers files are not covered
by make W=n and that these need to be checked separately with
scripts/kernel-doc.
[1] commit 3a025e1d1c2e ("Add optional check for bad kernel-doc comments")
Link: https://git.kernel.org/torvalds/c/3a025e1d1c2e
Fixes: 8fcce5803afd ("doc-guide: kernel-doc: add comment about formatting verification")
Signed-off-by: Vincent Mailhol <mailhol.vincent@xxxxxxxxxx>
---
CC: Matthew Wilcox <mawilcox@xxxxxxxxxxxxx>
CC: Jonathan Corbet <corbet@xxxxxxx>
The best would obviously be to modify scripts/Makefile.build to also
check headers, but this is easier said than done. Updating the
documentation is the best I can offer.
---
Documentation/doc-guide/kernel-doc.rst | 7 +++++--
1 file changed, 5 insertions(+), 2 deletions(-)
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 1dcbd7332476..c7785ee40e47 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -56,11 +56,14 @@ 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::
+The documentation format of ``.c`` files is also verified by the kernel build
+when it is requested to perform extra gcc checks::
make W=n
+However, the above command does not verify header files. These should be checked
+separately using ``kernel-doc``.
+
Function documentation
----------------------
--
2.25.1
