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

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

Em Mon, 01 Sep 2025 13:09:15 +0300
Jani Nikula <jani.nikula@intel.com> escreveu:

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

Not all, but those that are part of the kAPI requires good documentation.

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

Driver-specific functions could remain out of doc build - or be part
of the documentation. It should be a decision of the driver authors,
that may or may not be expecting contributions from the community.

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

Agreed. What I said is that this is a good start point, as it sounds
to me that we do have kAPI documentation inside headers but not
exported to the documentation.

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

Agreed. Things look better those days, but just because right now
there are several warnings disabled by default.

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

On media, our CI builds with W=1, and aim to have no warnings.

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

Good idea. If you have some time, feel free to propose some patches.

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

Checking the entire set of files inside the Kernel with kernel-doc
is fast. Using the new make mandocs, for instance, with reads the
entire tree takes about 45 seconds on my machine:

	$ time make mandocs
	...
	real    0m44,211s
	user    0m35,787s
	sys     0m3,274s

(and reports thousands of warnings)

Thanks,
Mauro