mirror of https://lore.kernel.org/lkml/
 help / color / mirror / Atom feed
From: 闲逛 <2368492046@qq.com>
To: corbet <corbet@lwn.net>, mchehab <mchehab@kernel.org>
Cc: wy <wy@wyuan.org>, linux-doc <linux-doc@vger.kernel.org>,
	skhan <skhan@linuxfoundation.org>,
	rdunlap <rdunlap@infradead.org>,
	linux-kernel <linux-kernel@vger.kernel.org>
Subject: [PATCH v2 3/4] docs: kernel-doc: honor environment warning error settings
Date: Sat, 14 Nov 2026 17:06:33 +0800	[thread overview]
Message-ID: <tencent_3F24F325BB81DAD964AD06F826A395C7FE07@qq.com> (raw)

From: yuehua-meng <2368492046@qq.com>

KCFLAGS=-Werror does not match the flag expression because it
requires a trailing slash. In addition, the CLI ignores the
resolved policy, so KDOC_WERROR=1 also returns success on warnings.

Remove the extra slash and use the resolved configuration to
choose the exit status. Test the CLI flag, both environment
settings, flag boundaries, and clean input. Preserve zero and empty
KDOC_WERROR overrides and explicit command-line -Werror precedence.

Fixes: 094a4845789b ("scripts/kernel-doc.py: add a Python parser")
Fixes: 802774d8539f ("docs: kdoc: avoid error_count overflows")

Signed-off-by: yuehua-meng <2368492046@qq.com>
---
Changes in v2:
Rebase onto docs-next; no functional change from the signed v1.

 tools/docs/kernel-doc               |  2 +-
 tools/lib/python/kdoc/kdoc_files.py |  6 ++---
 tools/unittests/test_kdoc_werror.py | 41 +++++++++++++++++++++++++++++
 3 files changed, 45 insertions(+), 4 deletions(-)
 create mode 100644 tools/unittests/test_kdoc_werror.py

diff --git a/tools/docs/kernel-doc b/tools/docs/kernel-doc
index d9192c3f1..1422bdb37 100755
--- a/tools/docs/kernel-doc
+++ b/tools/docs/kernel-doc
@@ -381,7 +381,7 @@ def main():
     if not error_count:
         sys.exit(0)
 
-    if args.werror:
+    if kfiles.config.werror:
         print("%s warnings as errors" % error_count)    # pylint: disable=C0209
         sys.exit(WERROR_RETURN_CODE)
 
diff --git a/tools/lib/python/kdoc/kdoc_files.py b/tools/lib/python/kdoc/kdoc_files.py
index 0118470aa..afc6f4487 100644
--- a/tools/lib/python/kdoc/kdoc_files.py
+++ b/tools/lib/python/kdoc/kdoc_files.py
@@ -251,7 +251,7 @@ class KernelFiles():
         if not werror:
             kcflags = os.environ.get("KCFLAGS", None)
             if kcflags:
-                match = re.search(r"(\s|^)-Werror(\s|$)/", kcflags)
+                match = re.search(r"(\s|^)-Werror(\s|$)", kcflags)
                 if match:
                     werror = True
 
@@ -259,8 +259,8 @@ class KernelFiles():
             # someone was calling it with the variable from outside the
             # kernel's build system
             kdoc_werror = os.environ.get("KDOC_WERROR", None)
-            if kdoc_werror:
-                werror = kdoc_werror
+            if kdoc_werror is not None:
+                werror = kdoc_werror not in ("", "0")
 
         if not logger:
            logger = logging.getLogger("kernel-doc")
diff --git a/tools/unittests/test_kdoc_werror.py b/tools/unittests/test_kdoc_werror.py
new file mode 100644
index 000000000..3823d71ee
--- /dev/null
+++ b/tools/unittests/test_kdoc_werror.py
@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: GPL-2.0
+"""Regression tests for kernel-doc warning-policy exit statuses."""
+
+from kdoc_cli_helper import KernelDocCliTest
+
+
+class TestKernelDocWerror(KernelDocCliTest):
+    def test_warning_exit_status(self):
+        source = self.source("warning.c", (
+            "/**\n * example - function with an undocumented parameter\n */\n"
+            "void example(int value) {}\n"
+        ))
+        cases = [
+            ({}, [], 0),
+            ({}, ["-Werror"], 3),
+            ({"KCFLAGS": "-Werror"}, [], 3),
+            ({"KCFLAGS": "-Wall -Werror -O2"}, [], 3),
+            ({"KCFLAGS": "-Wall\t-Werror"}, [], 3),
+            ({"KDOC_WERROR": "1"}, [], 3),
+            ({"KDOC_WERROR": "0"}, [], 0),
+            ({"KCFLAGS": "-Werror", "KDOC_WERROR": "0"}, [], 0),
+            ({"KCFLAGS": "-Werror", "KDOC_WERROR": ""}, [], 0),
+            ({"KDOC_WERROR": "0"}, ["-Werror"], 3),
+            ({"KCFLAGS": "-Werror=unused"}, [], 0),
+            ({"KCFLAGS": "-Wno-error"}, [], 0),
+        ]
+        for environment, args, expected in cases:
+            with self.subTest(environment=environment, args=args):
+                result = self.run_kdoc(*args, source, environment=environment)
+                self.assertIn("not described", result.stderr)
+                self.assertEqual(result.returncode, expected, result.stderr)
+
+    def test_clean_documentation_with_werror(self):
+        source = self.source("clean.c", (
+            "/**\n * example - documented function\n */\n"
+            "void example(void) {}\n"
+        ))
+        for environment in ({"KCFLAGS": "-Werror"}, {"KDOC_WERROR": "1"}):
+            with self.subTest(environment=environment):
+                result = self.run_kdoc(source, environment=environment)
+                self.assertEqual(result.returncode, 0, result.stderr)
-- 
2.53.0.windows.2


                 reply	other threads:[~2026-11-14  9:06 UTC|newest]

Thread overview: [no followups] expand[flat|nested]  mbox.gz  Atom feed

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=tencent_3F24F325BB81DAD964AD06F826A395C7FE07@qq.com \
    --to=2368492046@qq.com \
    --cc=corbet@lwn.net \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=mchehab@kernel.org \
    --cc=rdunlap@infradead.org \
    --cc=skhan@linuxfoundation.org \
    --cc=wy@wyuan.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox

all inboxes | Powered by JetHome®