[Intel-wired-lan] [PATCH 32/38] docs: kdoc_files: document KernelFiles() ABI

Mauro Carvalho Chehab
2026-02-18T10:13:45Z

The KernelFiles is the main entry point to run kernel-doc,
being used by both tools/docs/kernel-doc and
Documentation/sphinx/kerneldoc.py.

It is also used on QEMU, which also uses the kernel-doc
libraries from tools/lib/python/kdoc.

Properly describe its ABI contract.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
tools/lib/python/kdoc/kdoc_files.py | 44 ++++++++++++++++++++++++++++-
1 file changed, 43 insertions(+), 1 deletion(-)

diff --git a/tools/lib/python/kdoc/kdoc_files.py b/tools/lib/python/kdoc/kdoc_files.py
index c35e033cf123..8c2059623949 100644
--- a/tools/lib/python/kdoc/kdoc_files.py
+++ b/tools/lib/python/kdoc/kdoc_files.py
@@ -91,7 +91,49 @@ class KernelFiles():
"""
Parse kernel-doc tags on multiple kernel source files.

- There are two type of parsers defined here:
+ This is the main entry point to run kernel-doc. This class is initialized
+ using a series of optional arguments:
+
+ ``verbose``
+ If True, enables kernel-doc verbosity. Default: False.
+
+ ``out_style``
+ Class to be used to format output. If None (default),
+ only report errors.
+
+ ``xforms``
+ Transforms to be applied to C prototypes and data structs.
+ If not specified, defaults to xforms = CFunction()
+
+ ``werror``
+ If True, treat warnings as errors, retuning an error code on warnings.
+
+ Default: False.
+
+ ``wreturn``
+ If True, warns about the lack of a return markup on functions.
+
+ Default: False.
+ ``wshort_desc``
+ If True, warns if initial short description is missing.
+
+ Default: False.
+
+ ``wcontents_before_sections``
+ If True, warn if there are contents before sections (deprecated).
+ This option is kept just for backward-compatibility, but it does
+ nothing, neither here nor at the original Perl script.
+
+ Default: False.
+
+ ``logger``
+ Optional logger class instance.
+
+ If not specified, defaults to use: ``logging.getLogger("kernel-doc")``
+
+ Note:
+ There are two type of parsers defined here:
+
- self.parse_file(): parses both kernel-doc markups and
``EXPORT_SYMBOL*`` macros;
- self.process_export_file(): parses only ``EXPORT_SYMBOL*`` macros.
--
2.52.0