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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

On Tue, 03 Feb 2026 12:52:22 +0200
Jani Nikula <jani.nikula@linux.intel.com> wrote:

> 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.

I considered that, but on the other hand, if one wants to test
the intermediate internal KdocItem representation, having them
altogether helps to see what happened.

> And you can easily debug and compare the outputs with
> direct kernel-doc invocation. Etc.

True, but as I added support at kernel-doc to generate a yaml
format, it should be easy to diff from what someone wrote and
what kernel-doc actually produced - heh - sort of...

... pyyaml output is not user-friendly. Maybe there are ways
to make it use a more compact/nicer notation, but digging
into its documentation is not easy:

	https://pyyaml.org/wiki/PyYAMLDocumentation

and it is not complete.

> 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.

I'll take a look on it. Thanks for the hints!

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



Thanks,
Mauro