Re: [Ksummit-discuss] [TECH TOPIC] What kernel documentation could be

From: Liam Howlett <liam.howlett@oracle.com>
To: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Linus Torvalds <torvalds@linux-foundation.org>,
	Jonathan Corbet <corbet@lwn.net>,
	Jani Nikula <jani.nikula@intel.com>,
	ksummit <ksummit-discuss@lists.linuxfoundation.org>,
	"ksummit@lists.linux.dev" <ksummit@lists.linux.dev>,
	Markus Heiser <markus.heiser@darmarit.de>
Subject: Re: [Ksummit-discuss] [TECH TOPIC] What kernel documentation could be
Date: Mon, 27 Jun 2022 15:28:40 +0000	[thread overview]
Message-ID: <20220627152832.yigreu5ztnoxfp4g@revolver> (raw)
In-Reply-To: <20220626105306.122cdeda@sal.lan>

* Mauro Carvalho Chehab <mchehab@kernel.org> [220626 05:53]:
> Em Sun, 26 Jun 2022 08:55:24 +0100
> Mauro Carvalho Chehab <mchehab@kernel.org> escreveu:
> 
> > Em Sat, 25 Jun 2022 11:11:40 -0700
> > Linus Torvalds <torvalds@linux-foundation.org> escreveu:
> > 
> > > On Sat, Jun 25, 2022 at 7:00 AM Jonathan Corbet <corbet@lwn.net> wrote:  
> > > >
> > > > I said "some" - this was a proof-of-concept hack.  The complexity of
> > > > their symbol lookup code is ... daunting ... and not something that gets
> > > > fixed in one place.  More research is required...    
> > > 
> > > Note that at least for me, the issue with building docs isn't hugely
> > > performance related.
> > > 
> > > Yes, yes, it would be good if it was faster. But..
> > > 
> > > The primary problems I see with building the docs (and thus checking
> > > them, the same way I do an allmodconfig build test) is
> > > 
> > >  (a) it's insanely noisy, which makes and "check that it's ok" ENTIRELY USELESS.  
> > 
> > When the environment is set for building docs, almost all output there
> > are actually due to build errors/warnings that got introduced by patches
> > touching documentation that were never build-tested.
> > 
> > There are 4 components that report errors during "make htmldocs". 
> > 
> > 1. Documentation cross-reference check. 
> ...
> > 2. ABI documentation check:
> ...
> > 3. kernel-doc warnings.
> ...
> 
> Btw, once we fix the errors from the above checks, one of the things that 
> could be done in order to avoid noisy doc builds would be to run this 
> during normal Kernel build, if CONFIG_WERROR is set (and if .git is present
> at the source build dir):
> 
> 	./scripts/documentation-file-ref-check --warn
> 	./scripts/get_abi.pl validate
> 	./scripts/kernel-doc --none $(git grep kernel-doc $(git ls-files Documentation/|grep -v kernel-doc.rst)|perl -ne 'print "$1\n" if (m/kernel-doc::\s*(\S+)/);'|sort|uniq) 
> 
> aborting the build on such warnings.
> 
> On my notebook (i5-10210U), the above takes ~8 seconds to run. So, it 
> won't make much difference at the build time, and doing that would have
> avoided ~100 warnings during htmldocs build against current linux-next.
> 

Couldn't we add this to the build bots and ask the authors to fix the
commits?

Thanks,
Liam