Em Wed, 20 Jul 2016 20:35:09 +0200
Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu:
> Am 20.07.2016 um 14:20 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>:
>
> > Em Tue, 19 Jul 2016 14:36:50 +0200
> > Daniel Vetter <daniel@xxxxxxxx> 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@xxxxxxxxxxx>
> >>> Cc: Jonathan Corbet <corbet@xxxxxxx>
> >>> Cc: linux-doc@xxxxxxxxxxxxxxx
> >>> Signed-off-by: Daniel Vetter <daniel.vetter@xxxxxxxxx>
> >>
> >> 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?
What I mean is that, in order to solve typedefs, Sphinx would need to
parse all include files that contains typedefs, in order to discover if
a typedef argument is used, and parse such argument to the original one,
e. g., if we have something like:
typedef long int size_t;
it would need to replace "size_t" by "long int" internally, before being
able to produce an unique reference for a function that uses "size_t"
as an argument or returned value. However, AFAICT, Sphinx is not like
Doxygen: it doesn't parse header files. So, there's no easy fix.
On the other hand, the C domain is too simple: it assumes that
all functions, enums, etc are global, e. g. there should be just one
function called "ioctl", or "open".
So, both domains are broken by design.
I agree with you, however, that fixing the c domain seems to be easier.
It would require some way to let the user to force the cross reference
name, like, for example:
.. c:function::
:name: vidioc_ioctl
int ioctl( int fd, int request, struct v4l2_capability *argp )
Is it possible to extend the c-domain to do something like that and
still be backward-compatible with Sphinx 1.2?
Regards,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
