[Intel-gfx] [PATCH 2/2] drm/doc: Fix more kerneldoc/sphinx warnings

[Markus Heiser]

Am 20.07.2016 um 14:20 schrieb Mauro Carvalho Chehab <mchehab at s-opensource.com>:

> Em Tue, 19 Jul 2016 14:36:50 +0200
> Daniel Vetter <daniel at 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 at darmarit.de>
>>> Cc: Jonathan Corbet <corbet at lwn.net>
>>> Cc: linux-doc at vger.kernel.org
>>> Signed-off-by: Daniel Vetter <daniel.vetter at 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. 

There is a discussion about function overloading and identifiers

  https://github.com/sphinx-doc/sphinx/issues/2682#issuecomment-229515888

If we use the C-domain ("..c:function::"  instead of ".. cpp:function::")
this error did not expire. But using the C-domain has other drawbacks, we
discussed with ioctl.

May be it is better to switch to the c-domain and try to handle 
these drawbacks ... I don't know.

> I guess that the problem is because Sphinx tries to generate a CPP like
> function name for cross-ref, and such parser is unable to handle typedef
> arguments. IMHO, this is broken by design.

by design? 

-- Markus --

> 
> 
> Thanks,
> Mauro