[PATCH 00/38] docs: several improvements to kernel-doc

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

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/

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