Em Mon, 01 Sep 2025 13:09:15 +0300 Jani Nikula <jani.nikula@xxxxxxxxx> escreveu: > 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. 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
