[PATCH 00/38] docs: several improvements to kernel-doc
From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Date: 2026-02-18 10:13:18
Also in:
intel-wired-lan, linux-doc, linux-hardening, lkml
Hi Jon, This series contain several improvements for kernel-doc. Most of the patches came from v4 of this series: https://lore.kernel.org/linux-doc/cover.1769867953.git.mchehab+huawei@kernel.org/ (local) But I dropped from this series the unit tests part. I'll be sumitting it on a separate series. The rationale is that, when I converted kernel-doc from Perl, the goal were to produce a bug-compatible version. As anyone that worked before with kernel-doc are aware, using regex to handle C input is not great. Instead, we need something closer to how C statements and declarations are handled. Yet, to avoid breaking docs, I avoided touching the regex-based algorithms inside it with one exception: struct_group logic was using very complex regexes that are incompatible with Python internal "re" module. So, I came up with a different approach: NestedMatch. The logic inside it is meant to properly handle brackets, square brackets and parenthesis, which is closer to what C lexical parser does. On that time, I added a TODO about the need to extend that. The first part of this series do exactly that: it extends it to parse comma-separated arguments, respecting brackets and parenthesis. It then adds an "alias" to it at class CFunction. With that, specifying functions/macros to be handled becomes much easier. With such infra in place, it moves the transform functions to a separate file, making it hopefully easier to maintain. As a side effect, it also makes easier for other projects to use kernel-doc (I tested it on QEMU). Then, it adds support for newer kref annotations. The remaining patches on this series improve the man page output, making them more compatible with other man pages. - I wrote several unit tests to check kernel-doc behavior. I intend to submit them on the top of this series later on. Regards, Mauro Mauro Carvalho Chehab (36): docs: kdoc_re: add support for groups() docs: kdoc_re: don't go past the end of a line docs: kdoc_parser: move var transformers to the beginning docs: kdoc_parser: don't mangle with function defines docs: kdoc_parser: add functions support for NestedMatch docs: kdoc_parser: use NestedMatch to handle __attribute__ on functions docs: kdoc_parser: fix variable regexes to work with size_t docs: kdoc_parser: fix the default_value logic for variables docs: kdoc_parser: add some debug for variable parsing docs: kdoc_parser: don't exclude defaults from prototype docs: kdoc_parser: fix parser to support multi-word types docs: kdoc_parser: add support for LIST_HEAD docs: kdoc_re: properly handle strings and escape chars on it docs: kdoc_re: better show KernRe() at documentation docs: kdoc_re: don't recompile NestedMatch regex every time docs: kdoc_re: Change NestedMath args replacement to \0 docs: kdoc_re: make NestedMatch use KernRe docs: kdoc_re: add support on NestedMatch for argument replacement docs: kdoc_parser: better handle struct_group macros docs: kdoc_re: fix a parse bug on struct page_pool_params docs: kdoc_re: add a helper class to declare C function matches docs: kdoc_parser: use the new CFunction class docs: kdoc_parser: minimize differences with struct_group_tagged docs: kdoc_parser: move transform lists to a separate file docs: kdoc_re: don't remove the trailing ";" with NestedMatch docs: kdoc_re: prevent adding whitespaces on sub replacements docs: xforms_lists.py: use CFuntion to handle all function macros docs: kdoc_files: allows the caller to use a different xforms class docs: kdoc_re: Fix NestedMatch.sub() which causes PDF builds to break docs: kdoc_files: document KernelFiles() ABI docs: kdoc_output: add optional args to ManOutput class docs: sphinx-build-wrapper: better handle troff .TH markups docs: kdoc_output: use a more standard order for .TH on man pages docs: sphinx-build-wrapper: don't allow "/" on file names docs: kdoc_output: describe the class init parameters docs: kdoc_output: pick a better default for modulename Randy Dunlap (2): docs: kdoc_parser: ignore context analysis and lock attributes docs: kdoc_parser: handle struct member macro VIRTIO_DECLARE_FEATURES(name) Documentation/tools/kdoc_parser.rst | 8 + tools/docs/kernel-doc | 1 - tools/docs/sphinx-build-wrapper | 9 +- tools/lib/python/kdoc/kdoc_files.py | 54 +++++- tools/lib/python/kdoc/kdoc_output.py | 73 ++++++-- tools/lib/python/kdoc/kdoc_parser.py | 183 ++++--------------- tools/lib/python/kdoc/kdoc_re.py | 242 ++++++++++++++++++++------ tools/lib/python/kdoc/xforms_lists.py | 109 ++++++++++++ 8 files changed, 451 insertions(+), 228 deletions(-) create mode 100644 tools/lib/python/kdoc/xforms_lists.py -- 2.52.0