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

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

On Tue, Sep 02, 2025 at 03:07:53PM +0300, Jani Nikula wrote:
> On Tue, 02 Sep 2025, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> > 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.
> 
> I'm not sure how that is relevant to what I'm saying.

You said that the building system lacks support of W=1/-Wall per
subsystem. What I said is that, provided that we add a:

	.. kernel-doc:: drivers/drm/...
	:wall: 

you can set it per file inside a subsystem. Granted: this is doesn't
cover the entire subsystem.

Heh, there is another option. For instance lets assume you want
-Wall for drm subsystem. you could have this on your CI:

	$ ./scripts/kernel-doc -Wall --none drivers/gpu/

On a similar way, the build system can also W=1 inside a subsystem:

	$ make W=1 drivers/gpu/

(This is what we do on media)

In the specific case of the drm subsystem, you could try to modify
dim to run both as a condition to accept a git push - or modify
CI to only actually do the merge after passing both.

-- 
Thanks,
Mauro