On Sun, 31 Aug 2025, Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> 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
