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

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

Em Tue, 02 Sep 2025 13:42:45 +0300
Jani Nikula <jani.nikula@intel.com> escreveu:

> On Mon, 01 Sep 2025, Randy Dunlap <rdunlap@infradead.org> wrote:
> > 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.  
> 
> I think in general the build system lacks proper support for subsystems
> or drivers being ahead of the curve in keeping them W=1 or kernel-doc
> -Wall clean.

It is trivial to add a spinx/kerneldoc parameter to allow setting
-Wall per each .. kernel-doc markup. Yet, one would need to add it
for every markup within the subsystem.

It is probably easier to do something similar to that via a CI.

> 
> We hack around this in parts of drm Makefiles, and it really has helped
> to keep the kernel-doc and W=1 breakage/fix churn down. But it's not
> pretty.
> 
> 
> BR,
> Jani.
> 



Thanks,
Mauro