[PATCH v2 1/4] docs: kernel-doc: pass transforms when parsing export files

From: 闲逛

Date: Sat Nov 14 2026 - 04:06:48 EST


From: yuehua-meng <2368492046@xxxxxx>

A separate -export-file reaches a KernelDoc constructor call that
does not pass the required xforms argument, raising TypeError.

Pass the configured transforms just as parse_file() does. Add a
regression with declarations in a header and an export in a
separate source file; only the exported declaration is emitted.

Fixes: d842057c4a20 ("docs: kdoc_parser: move transform lists to a separate file")

Signed-off-by: yuehua-meng <2368492046@xxxxxx>
---
Changes in v2:
Rebase onto docs-next. Place the parser fix and shared CLI helper
before the combined-export regression tests.

tools/lib/python/kdoc/kdoc_files.py | 2 +-
tools/unittests/kdoc_cli_helper.py | 34 ++++++++++++++++++++++++
tools/unittests/test_kdoc_export_file.py | 19 +++++++++++++
3 files changed, 54 insertions(+), 1 deletion(-)
create mode 100644 tools/unittests/kdoc_cli_helper.py
create mode 100644 tools/unittests/test_kdoc_export_file.py

diff --git a/tools/lib/python/kdoc/kdoc_files.py b/tools/lib/python/kdoc/kdoc_files.py
index ed82b6e6a..d39b15edd 100644
--- a/tools/lib/python/kdoc/kdoc_files.py
+++ b/tools/lib/python/kdoc/kdoc_files.py
@@ -212,7 +212,7 @@ class KernelFiles():
if fname in self.export_files:
return

- doc = KernelDoc(self.config, fname)
+ doc = KernelDoc(self.config, fname, self.xforms)
export_table = doc.parse_export()

if not export_table:
diff --git a/tools/unittests/kdoc_cli_helper.py b/tools/unittests/kdoc_cli_helper.py
new file mode 100644
index 000000000..e15b7f00e
--- /dev/null
+++ b/tools/unittests/kdoc_cli_helper.py
@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: GPL-2.0
+"""Helpers for running kernel-doc against temporary source files."""
+
+import os
+from pathlib import Path
+import subprocess
+import sys
+import tempfile
+import unittest
+
+
+class KernelDocCliTest(unittest.TestCase):
+ def setUp(self):
+ temporary = tempfile.TemporaryDirectory()
+ self.addCleanup(temporary.cleanup)
+ self.directory = Path(temporary.name)
+ self.command = Path(__file__).resolve().parent.parent / "docs/kernel-doc"
+
+ def source(self, name, content):
+ path = self.directory / name
+ path.write_text(content, encoding="utf-8")
+ return path
+
+ def run_kdoc(self, *args, environment=None, no_site=False, cwd=None):
+ env = os.environ.copy()
+ for key in ("KCFLAGS", "KDOC_WERROR", "KBUILD_VERBOSE", "SRCTREE"):
+ env.pop(key, None)
+ env.update(environment or {})
+ command = [sys.executable, "-B"]
+ if no_site:
+ command.extend(["-I", "-S"])
+ command.extend([str(self.command), *map(str, args)])
+ return subprocess.run(command, env=env, cwd=cwd, capture_output=True,
+ text=True, encoding="utf-8", timeout=30)
diff --git a/tools/unittests/test_kdoc_export_file.py b/tools/unittests/test_kdoc_export_file.py
new file mode 100644
index 000000000..9d2790780
--- /dev/null
+++ b/tools/unittests/test_kdoc_export_file.py
@@ -0,0 +1,19 @@
+# SPDX-License-Identifier: GPL-2.0
+"""Regression test for a separate kernel-doc export source file."""
+
+from kdoc_cli_helper import KernelDocCliTest
+
+
+class TestKernelDocExportFile(KernelDocCliTest):
+ def test_explicit_export_file(self):
+ source = self.source("example.h", (
+ "/**\n * alpha - internal function\n */\n"
+ "void alpha(void);\n"
+ "/**\n * beta - exported function\n */\n"
+ "void beta(void);\n"
+ ))
+ exports = self.source("exports.c", "EXPORT_SYMBOL(beta);\n")
+ result = self.run_kdoc("-export", "-export-file", exports, source)
+ self.assertEqual(result.returncode, 0, result.stderr)
+ self.assertNotIn("void alpha", result.stdout)
+ self.assertIn("void beta", result.stdout)
--
2.53.0.windows.2