Re: [PATCH 0/3] Some kernel-doc fixes

[Jani Nikula <jani.nikula@linux.intel.com>]

On Mon, 02 Feb 2026, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> As a heads up, I'm working on a separate set of patches that, if 
> things go well, we may end having a regression test for kernel-doc.
> When done, I'll be submitting in separate.
>
> The idea is to have a YAML file with source code, KdocItem,
> man output and rst output, and a dynamic unit test to run
> them. I finished today to write a skeleton, but still requires
> polishing (*).

...

> If you're curious enough, this is the test YAML file it is using to
> generate the 3 dynamic unit tests:

FWIW, I think it'll be painful to have the source and the expected
result in the same YAML file, simply because all parts of this are fussy
about whitespace and indentation. I'd put them all in separate files,
with the YAML tying them together. Then you can also reuse a single
source file with multiple tests with different parameters and different
outputs. And you get editor syntax higlighting and other help for the
individual files. And you can easily debug and compare the outputs with
direct kernel-doc invocation. Etc.

In fact, this is exactly what I've done with Hawkmoth tests
[1][2]. There's years of experience poured into this. I test everything
through the parser directly, through the command-line, and through
Sphinx.


BR,
Jani.


[1] https://github.com/jnikula/hawkmoth/blob/master/doc/developer/testing.rst
[2] https://github.com/jnikula/hawkmoth/tree/master/test


-- 
Jani Nikula, Intel