Re: [TECH TOPIC] Kernel documentation - update and future directions

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

On Sun, 31 Aug 2025, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> It shouldn't be that hard to do the same for kernel-doc kAPI documentation:
> kernel-doc now can parse the entire tree with:
>
> 	$ scripts/kernel-doc .
>
> Someone can easily use it to discover the current gaps at the docs that
> have already some kernel-doc markups and identify what of them aren't
> yet placed under Documentation/ ".. kernel-doc::" markups.
>
> So, I'd say the first step here would be to ensure that 100% of the
> docs are there somewhere. Alternatively, we could place all the rest
> of functions with kernel-doc markups outside Documentation inside an
> "others/" book - or even "<subsystem>/others/", and then gradually move
> them to the right places.

I don't agree that all the kernel-docs need to be in the html build in
the first place. Some of them would be better off with a simple
non-structured comment instead. For example, most static functions. Some
of the kernel-docs are useful for the structure the format provides, but
still having them in the html build is overkill. For example, many
complex but driver specific functions.

I think the API documentation in the Sphinx build is primarily useful
for kernel generic and subsystem APIs, or overviews of
functionality. But nobody's looking at the Sphinx build for highly
specific and isolated documentation for individual structures or
functions.

I'd say emphasize quality over quantity in the Sphinx build. An
overwhelming amount of (in the big picture) insignificant API
documentation does not make for good documentation.

That said, there *are* a lot of kernel-doc comments that absolutely
should be pulled into the Sphinx build. But don't be indiscriminate
about it.

---

I think a more interesting first step would be ensuring all the
kernel-docs we do have are free of kernel-doc and rst warnings. Because
they should be, and this would make them easier to pull into the Sphinx
build as needed.

Currently we only have the kernel-doc checks in W=1 builds for .c
files.

The i915 and xe drivers have local Makefile hacks to do it for more than
just W=1 builds and also headers. The attempts to expand the header
checks to the drm subsystem, however, failed infamously.

And still none of this checks for rst. But now that kernel-doc is
python, it shouldn't be too hard. Probably needs a dependency, but it
could only depend on it when passing some --lint-rst option.

Having this in place would also reduce the churn caused by merging
broken kernel-doc. It's fast enough to be done as part of the regular
build, while most people don't run the entire Sphinx build as part of
the development flow.


BR,
Jani.


-- 
Jani Nikula, Intel