From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mauro Carvalho Chehab Subject: Re: [PATCH 2/2] drm/doc: Fix more kerneldoc/sphinx warnings Date: Fri, 22 Jul 2016 12:06:51 -0300 Message-ID: <20160722120651.4682b3d8@recife.lan> References: <1468928575-11309-1-git-send-email-daniel.vetter@ffwll.ch> <1468928575-11309-2-git-send-email-daniel.vetter@ffwll.ch> <20160719123650.GP17101@phenom.ffwll.local> <20160720092049.4501a08d@recife.lan> Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Return-path: In-Reply-To: Sender: linux-doc-owner@vger.kernel.org To: Markus Heiser Cc: Daniel Vetter , DRI Development , Intel Graphics Development , Daniel Vetter , Jonathan Corbet , linux-doc@vger.kernel.org, Daniel Vetter , Jani Nikula List-Id: intel-gfx@lists.freedesktop.org Em Wed, 20 Jul 2016 20:35:09 +0200 Markus Heiser escreveu: > Am 20.07.2016 um 14:20 schrieb Mauro Carvalho Chehab : > > > Em Tue, 19 Jul 2016 14:36:50 +0200 > > Daniel Vetter 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 > >>> Cc: Jonathan Corbet > >>> Cc: linux-doc@vger.kernel.org > >>> Signed-off-by: Daniel Vetter > >> > >> 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