Re: Troubles with kernel-doc and RST files

[Mauro Carvalho Chehab <mchehab@s-opensource.com>]

Em Tue, 19 Jul 2016 17:16:35 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Sun, 17 Jul 2016 10:01:54 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > 3) When there's an asterisk inside the source code, for example, to
> > document a pointer, or when something else fails when parsing a
> > header file, kernel-doc handler just outputs:
> > 	/devel/v4l/patchwork/Documentation/media/kapi/mc-core.rst:137: WARNING: Inline emphasis start-string without end-string.
> > 	/devel/v4l/patchwork/Documentation/media/kapi/mc-core.rst:470: WARNING: Explicit markup ends without a blank line; unexpected unindent.
> > 
> > pointing to a fake line at the rst file, instead of pointing to the
> > line inside the parsed header where the issue was detected, making
> > really hard to identify what's the error.
> > 
> > In this specific case, mc-core.rst has only 260 lines at the time I got
> > such error.  
> 
> This sounds like the same warning issue that Daniel was dealing with.
> Hopefully his config change will at least make these easier to deal with.
> 
> I wonder, though, if we could make kernel-doc a little smarter about
> these things so that the Right Thing happens for this sort of inadvertent
> markup?  If we could just recognize and escape a singleton *, that would
> make a lot of things work.

Yeah, that would be the best, but still, if some error happens, we need
the real line were it occurred, as it doesn't make sense to point to
a line that doesn't exist.


Thanks,
Mauro