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

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

Em Mon, 1 Sep 2025 09:51:01 -0700
Randy Dunlap <rdunlap@infradead.org> escreveu:

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

Sure, but on the other hand, lots of those have warnings. Even if
not part of htmldocs, IMO the kernel-doc markups should reflect the
actual code.

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

We can run it without actually building htmldocs. The only requirement
is to have Python 3.6 or above (this is enough to get error reports,
but 3.7 is needed to avoid having struct/function parameters out of
order).

The real problem is that, when we start doing it, Kernel build will 
have thousands of warnings. 

Perhaps one solution would be to have an image of our current
problems on a file, reporting only new stuff by default and using
WERROR policy, causing build to fail on new warnings.

This would at least avoid the problem to increase.

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

It is a lot more if you check warnings for files with kernel-doc outside 
the htmldocs build and if you enable all kdoc warnings:

	$ time ./scripts/kernel-doc -Wall . --none 2>warnings

	real    0m33,063s
	user    0m31,233s
	sys     0m0,753s

	$ grep Warning warnings|wc -l
	36965

almost 37K warnings.


Thanks,
Mauro