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=...
I was able to fix the other two typedef warnings with: https://git.linuxtv.org/mchehab/experimental.git/commit/?h=docs-next&id=...
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