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

From: Mauro Carvalho Chehab <mchehab@kernel.org>
To: Linus Torvalds <torvalds@linux-foundation.org>
Cc: Jonathan Corbet <corbet@lwn.net>,
	Jani Nikula <jani.nikula@intel.com>,
	ksummit <ksummit-discuss@lists.linuxfoundation.org>,
	ksummit@lists.linux.dev,
	Markus Heiser <markus.heiser@darmarit.de>
Subject: Re: [Ksummit-discuss] [TECH TOPIC] What kernel documentation could be
Date: Sun, 26 Jun 2022 10:53:06 +0100	[thread overview]
Message-ID: <20220626105306.122cdeda@sal.lan> (raw)
In-Reply-To: <20220626085524.42ee92c0@sal.lan>

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.

Regards,
Mauro