[PATCH] doc-guide: kernel-doc: specify that W=n does not check header files

[PATCH] doc-guide: kernel-doc: specify that W=n does not check header files

[Vincent Mailhol]

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@kernel.org>
---
This is a resend of a patch which I sent more than two years ago, on
which I got no answers and which I then forgot about.

Link: https://lore.kernel.org/all/20230531093951.358769-1-mailhol.vincent@wanadoo.fr/
---
 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 fd89a6d56ea9..9ebcb2da8606 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
 ----------------------
 

---
base-commit: efc362716ef356f3bb2e9584be1f4d61dbb39eb6
change-id: 20251225-doc-format-check-3d75ae190c8d

Best regards,
-- 
Vincent Mailhol <mailhol@kernel.org>

Re: [PATCH] doc-guide: kernel-doc: specify that W=n does not check header files

[Jonathan Corbet]

Vincent Mailhol <mailhol@kernel.org> writes:

> 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@kernel.org>
> ---
> This is a resend of a patch which I sent more than two years ago, on
> which I got no answers and which I then forgot about.
>
> Link: https://lore.kernel.org/all/20230531093951.358769-1-mailhol.vincent@wanadoo.fr/
> ---
>  Documentation/doc-guide/kernel-doc.rst | 7 +++++--
>  1 file changed, 5 insertions(+), 2 deletions(-)

Applied, thanks.

jon