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

[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)
      ------------------------------------------------------------------------------------------------------^

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.


Thanks,
Mauro