Re: [PATCH 2/2] drm/doc: Fix more kerneldoc/sphinx warnings

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

Em Wed, 20 Jul 2016 20:35:09 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> Am 20.07.2016 um 14:20 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> 
> > Em Tue, 19 Jul 2016 14:36:50 +0200
> > Daniel Vetter <daniel@ffwll.ch> escreveu:
> >   
> >> On Tue, Jul 19, 2016 at 01:42:55PM +0200, Daniel Vetter wrote:  
> >>> These are the leftovers I could only track down using keep_warnings =
> >>> True. For some of them we might want to update our style guide on how
> >>> to reference structures and constants, not sure ...
> >>> 
> >>> Cc: Markus Heiser <markus.heiser@darmarit.de>
> >>> Cc: Jonathan Corbet <corbet@lwn.net>
> >>> Cc: linux-doc@vger.kernel.org
> >>> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>    
> >> 
> >> Aside: With this and the latest docs-next branch from Jon it's possible to
> >> compile test doc changes (e.g. with git rebase -x) using:
> >> 
> >> $ make IGNORE_DOCBOOKS=1 SPHINXOPTS=-W htmldocs  
> > 
> > Unfortunately, we'll not get rid of Sphinx warnings any time soon.
> > 
> > The Sphinx function parser is really broken, even on version 1.4.5.
> > 
> > Every time Sphinx finds a typedef argument or return value, like here:
> > 
> > 	ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len);
> > 
> > It produces a very ugly noisy warning:
> > 
> > ./drivers/media/dvb-core/dvb_ringbuffer.h:149: WARNING: Error when parsing function declaration.
> > If the function has no return type:
> >  Error in declarator or parameters and qualifiers
> >  Invalid definition: Expecting "(" in parameters_and_qualifiers. [error at 8]
> >    ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
> >    --------^
> > If the function has a return type:
> >  Error in declarator or parameters and qualifiers
> >  If pointer to member declarator:
> >    Invalid definition: Expected '::' in pointer to member (function). [error at 37]
> >      ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
> >      -------------------------------------^
> >  If declarator-id:
> >    Invalid definition: Expecting "," or ")" in parameters_and_qualifiers, got "*". [error at 102]
> >      ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
> >      ------------------------------------------------------------------------------------------------------^
> >   
> 
> Aaargh ... it seems you are right. 

Just sent a fix for the above:
	https://git.linuxtv.org/mchehab/experimental.git/commit/?h=docs-next&id=263bbae9c1bf6ea7c14dad8c29f9b3148b2b5de7

I was able to fix the other two typedef warnings with:
	https://git.linuxtv.org/mchehab/experimental.git/commit/?h=docs-next&id=b32909983ab03e03504bb44d5c66f44b9d57adc3

Basically, I had to:

1) Make kernel-doc ignore __user;
2) typedef the function argument for v4l2_ctrl_add_handler();
3) not let kernel-doc generate :cpp:function: for function typedefs.

With DocBook, we used kernel-doc to produce a page for typedef
functions. Now, such capability got lost. Not sure if/how
Sphinx would support it.

Thanks,
Mauro