From adcb44b4ad0cb427bafaa04bd1c0096c94880bc0 Mon Sep 17 00:00:00 2001
From: yuehua-meng <2368492046@qq.com>
Date: Sat, 14 Nov 2026 13:15:23 +0800
Subject: [PATCH 2/4] docs: kernel-doc: honor environment warning error
 settings

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 the KDOC_WERROR=0
override and the precedence of an explicit command-line -Werror.
Empty KDOC_WERROR also disables the environment-derived policy.

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

AI assistance (Codex) was used to reproduce the failures, prepare
the fixes and regression tests, and execute the tests. The task was
to inspect and repair kernel-doc behavior in a local Linux tree.

Signed-off-by: yuehua-meng <2368492046@qq.com>
---
 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 feaf27b63..8555433bb 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