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