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

[Randy Dunlap <rdunlap@infradead.org>]

On 9/1/25 3:09 AM, Jani Nikula wrote:
> 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.


IMO there are far too many static functions that use kernel-doc notation.
I certainly don't want to discourage function documentation, but I don't
think there was any ever intent to have those functions added to the
kernel docbooks.


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

ISTM that there are lots of non-docs developers who either just don't care
about that or never run 'make W=1 htmldocs' to see the problems in their
drivers or subsystems. OK, maybe it's just a very low priority for them.

Willy had a suggestion that we just make checking kernel-doc during
all .c builds a permanent feature instead of a W=1 option.
This helps, but still doesn't force 'make htmldocs' to be run.

And it causes around 450 build warnings in my testing of an x86_64 allmodconfig
build.

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

-- 
~Randy