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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [day] [month] [year] [list]

Message-Id: <20230531093951.358769-1-mailhol.vincent@wanadoo.fr>
Date:   Wed, 31 May 2023 18:39:51 +0900
From:   Vincent Mailhol <mailhol.vincent@...adoo.fr>
To:     Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org
Cc:     Daniel Xu <dxu@...uu.xyz>, Sven Van Asbroeck <thesven73@...il.com>,
        Michael Ellerman <mpe@...erman.id.au>,
        Miguel Ojeda <ojeda@...nel.org>,
        Akira Yokosawa <akiyks@...il.com>,
        Mike Rapoport <rppt@...ux.vnet.ibm.com>,
        linux-kernel@...r.kernel.org,
        Simon Horman <simon.horman@...igine.com>,
        Vincent Mailhol <mailhol.vincent@...adoo.fr>,
        Matthew Wilcox <mawilcox@...rosoft.com>
Subject: [PATCH v1] doc-guide: kernel-doc: specify that W=n does not check header files

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@...adoo.fr>
---
CC: Matthew Wilcox <mawilcox@...rosoft.com>
CC: Jonathan Corbet <corbet@....net>

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