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

From: Christian Brauner <brauner@kernel.org>
To: Liam Howlett <liam.howlett@oracle.com>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>,
	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 17:54:52 +0200	[thread overview]
Message-ID: <20220627155452.uwxnpbjh3z4efzif@wittgenstein> (raw)
In-Reply-To: <20220627152832.yigreu5ztnoxfp4g@revolver>

On Mon, Jun 27, 2022 at 03:28:40PM +0000, Liam Howlett wrote:
> * 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?

Isn't for-next already integrated? Maybe not. I got a mail from Andrew
telling me I had a kernel-doc copy-paste error.

Integration with build-bots would be great. I generally aim to add
kernel-doc for all non-trivial code that I add. But during different
patchset versions copy-paste errors do sometimes happen (e.g., for git
grep/sed calls).