Re: Troubles with kernel-doc and RST files

[Mauro Carvalho Chehab <mchehab@s-opensource.com>]

Em Tue, 19 Jul 2016 17:01:33 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Sun, 17 Jul 2016 10:01:54 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > 2) For functions, kernel-doc is now an all or nothing. If not all
> > functions are declared, it outputs this warning:
> > 
> > 	./include/media/media-devnode.h:1: warning: no structured comments
> > 
> > And give up. No functions are exported, nor it points where it bailed.
> > So, we need to manually look into all exported symbols to identify
> > what's missing  
> 
> So could you describe this one in a bit more detail?  An example of a
> file with the problem and associated kernel-doc directive would be most
> helpful here.  This sounds like something we definitely want to fix.

I actually noticed it when I was checking for the documentation generated
by the RC header file. There, I had to add documentation for several
functions:
	https://git.linuxtv.org/media_tree.git/commit/?h=docs-next&id=5b6137dc84f627e8497e554890ae02378c54f9f0

Without that, I had an error like the above, and no functions were
documented.

I didn't further tried to investigate the root cause.

One thing I noticed is that Sphinx is very poor on detecting some types
of changes, and we need to wipe out the Sphinx docs after some changes, 
as otherwise the document won't be ok. Maybe that's the case.

Another possibility is that the all or nothing behavior happens when
the :export: attribute is used.


Thanks,
Mauro