Re: [PATCH 00/10] Fix documentation warnings at linux-next

[Mauro Carvalho Chehab]

Em Fri, 15 Jan 2021 13:05:56 +0100
Lukas Bulwahn <lukas.bulwahn@xxxxxxxxx> escreveu:

> On Fri, Jan 15, 2021 at 10:49 AM Mauro Carvalho Chehab
> <mchehab+huawei@xxxxxxxxxx> wrote:
> >
> > Hi Lukas,
> >
> > Em Fri, 15 Jan 2021 07:12:38 +0100
> > Lukas Bulwahn <lukas.bulwahn@xxxxxxxxx> escreveu:
> >  
> > > [reduced the recipient list to the main responsible ones and list]
> > >
> > > Hi Mauro, hi Jonathan,
> > >
> > > We both, Mauro and I, have been submitting patches to address the
> > > documentation warnings on linux-next. If it is okay with you, Mauro, I
> > > would like to take responsibility for the task to send out the patches
> > > to address all warnings on linux-next in make htmldocs and follow up
> > > with all the discussions. I can also provide a short weekly summary
> > > (probably always on Friday) on what is pending where and what I could
> > > not resolve by myself.
> > >
> > > Is that okay for you?
> > >
> > > If at some point I do not have the time to take care anymore, I will
> > > let you know.  
> >
> > Yeah, sure!
> >
> > Anyway, after applying the patches I sent this week, the warnings
> > I'm getting are all due to the validation scripts I wrote. So, if
> > everything gets merged (either yours or my version), we'll have zero
> > Sphinx/kernel-doc warnings again.
> >  
> 
> It is a never ending story... I already have seen two new warnings on
> today's linux-next and sent out patches.

Yes, I know. After 5.10, it is easier to track new stuff, as
Sphinx/kernel-doc warnings were all shut up there.

> 
> > $ scripts/documentation-file-ref-check
> > $ scripts/get_abi.pl validate  
> 
> I will also try out those two scripts, but I cannot commit to
> follow-up on all of those yet. 

Yeah, some of those are not trivial to address.

FYI, those are called by default after make allmodconfig/allyesconfig.

> I am also looking into addressing all
> kerneldoc warnings, even if not pulled in by make htmldocs.

Make sense. There are lots of kerneldoc warnings for files that 
aren't currently part of the docs building system. It makes sense to
fix those and add them to the Sphinx build logic.

Here, I have a local script that checks for those:

	for i in $(git grep -h "\.\.\s*kernel-doc::" Documentation/|cut -d':' -f 3|grep -vE "\bsource$"|sort|uniq); do
		./scripts/kernel-doc --none $i
	done

It reports 101 warnings against next-20210114.

Thanks,
Mauro