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

[Mauro Carvalho Chehab]

Em Fri, 15 Jan 2021 13:36:23 +0100
Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> escreveu:

> 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.

In time: those are for the ones that are included, but that
doesn't have all symbols added. I have another one somewhere
that does a more deeply check. I submitted it as a RFC sometime
ago to the docs ML:

	https://git.linuxtv.org/mchehab/experimental.git/tree/scripts/docs_check_exports?h=doc_export_symbol&id=3f7d1e1b0bcdbe1d95eaa4b256259dfaa08faece

Such script checks only exported symbols.

Thanks,
Mauro