Troubles with kernel-doc and RST files

Troubles with kernel-doc and RST files

[Mauro Carvalho Chehab]

I'm now converting the kAPI media doc to RST file, and I'm seeing several
issues with kernel-doc conversion:

1) We now need to include each header file with documentation twice,
one to get the enums, structs, typedefs, ... and another one for the
functions:

	.. kernel-doc:: include/media/media-device.h

	.. kernel-doc:: include/media/media-entity.h
	   :export: drivers/media/media-entity.c

2) For functions, kernel-doc is now an all or nothing. If not all
functions are declared, it outputs this warning:

	./include/media/media-devnode.h:1: warning: no structured comments

And give up. No functions are exported, nor it points where it bailed.
So, we need to manually look into all exported symbols to identify
what's missing

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.

4) There are now several errors when parsing functions. Those seems to
happen when an argument is a function pointer, like:

/devel/v4l/patchwork/Documentation/media/kapi/v4l2-core.rst:757: WARNING: Error when parsing function declaration.
If the function has no return type:
  Error in declarator or parameters and qualifiers
  Invalid definition: Expected identifier in nested name, got keyword: int [error at 3]
    int v4l2_ctrl_add_handler (struct v4l2_ctrl_handler * hdl, struct v4l2_ctrl_handler * add, bool (*filter) (const struct v4l2_ctrl *ctrl)
    ---^
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 26]
      int v4l2_ctrl_add_handler (struct v4l2_ctrl_handler * hdl, struct v4l2_ctrl_handler * add, bool (*filter) (const struct v4l2_ctrl *ctrl)
      --------------------------^
  If declarator-id:
    Invalid definition: Expecting "," or ")" in parameters_and_qualifiers, got "EOF". [error at 136]
      int v4l2_ctrl_add_handler (struct v4l2_ctrl_handler * hdl, struct v4l2_ctrl_handler * add, bool (*filter) (const struct v4l2_ctrl *ctrl)
      ----------------------------------------------------------------------------------------------------------------------------------------^

The same happens for function typedefs:

/devel/v4l/patchwork/Documentation/media/kapi/v4l2-core.rst:16: WARNING: Error when parsing function declaration.
If the function has no return type:
  Error in declarator or parameters and qualifiers
  Invalid definition: Expected identifier in nested name, got keyword: typedef [error at 7]
    typedef bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle)
    -------^
If the function has a return type:
  Invalid definition: Expected identifier in nested name, got keyword: typedef [error at 7]
    typedef bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle)
    -------^
/devel/v4l/patchwork/Documentation/media/kapi/v4l2-core.rst:298: WARNING: Error when parsing function declaration.
If the function has no return type:
  Error in declarator or parameters and qualifiers
  Invalid definition: Expected identifier in nested name, got keyword: int [error at 3]
    int v4l2_ctrl_add_handler (struct v4l2_ctrl_handler * hdl, struct v4l2_ctrl_handler * add, bool (*filter) (const struct v4l2_ctrl *ctrl)
    ---^
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 26]
      int v4l2_ctrl_add_handler (struct v4l2_ctrl_handler * hdl, struct v4l2_ctrl_handler * add, bool (*filter) (const struct v4l2_ctrl *ctrl)
      --------------------------^
  If declarator-id:
    Invalid definition: Expecting "," or ")" in parameters_and_qualifiers, got "EOF". [error at 136]
      int v4l2_ctrl_add_handler (struct v4l2_ctrl_handler * hdl, struct v4l2_ctrl_handler * add, bool (*filter) (const struct v4l2_ctrl *ctrl)
      ----------------------------------------------------------------------------------------------------------------------------------------^

Could someone more familiar to Sphinx kernel-doc take a look on the
above?

Thanks,
Mauro

Re: Troubles with kernel-doc and RST files

[Jonathan Corbet]

[Back home and trying to get going on stuff for real.  I'll look at the
issues listed in this message one at a time.]

On Sun, 17 Jul 2016 10:01:54 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

> 1) We now need to include each header file with documentation twice,
> one to get the enums, structs, typedefs, ... and another one for the
> functions:
> 
> 	.. kernel-doc:: include/media/media-device.h
> 
> 	.. kernel-doc:: include/media/media-entity.h
> 	   :export: drivers/media/media-entity.c

So I'm a little confused here; you're including from two different header
files here.  Did you want media-entity.h in both directives?

If I do a simple test with a single line:

	.. kernel-doc:: include/media/media-entity.h

I get everything - structs, functions, etc. - as I would expect.  Are you
seeing something different?

It probably would be nice to have an option for "data structures, doc
sections, and exported functions only" at some point.

Thanks,

jon

Re: Troubles with kernel-doc and RST files

[Mauro Carvalho Chehab]

Em Sun, 17 Jul 2016 20:37:19 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> [Back home and trying to get going on stuff for real.  I'll look at the
> issues listed in this message one at a time.]
> 
> On Sun, 17 Jul 2016 10:01:54 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > 1) We now need to include each header file with documentation twice,
> > one to get the enums, structs, typedefs, ... and another one for the
> > functions:
> > 
> > 	.. kernel-doc:: include/media/media-device.h
> > 
> > 	.. kernel-doc:: include/media/media-entity.h
> > 	   :export: drivers/media/media-entity.c  
> 
> So I'm a little confused here; you're including from two different header
> files here.  Did you want media-entity.h in both directives?

Yeah, on my patch I was including every header twice. The first
one to get the structs:

.. kernel-doc:: include/media/media-device.h

.. kernel-doc:: include/media/media-devnode.h

.. kernel-doc:: include/media/media-entity.h

And the next one to get the functions:

.. kernel-doc:: include/media/media-device.h
   :export: drivers/media/media-device.c

.. kernel-doc:: include/media/media-entity.h
   :export: drivers/media/media-entity.c


> If I do a simple test with a single line:
> 
> 	.. kernel-doc:: include/media/media-entity.h
> 
> I get everything - structs, functions, etc. - as I would expect.  Are you
> seeing something different?

Weird, now it worked... I noticed this issue because some of the cross
references were broken if I didn't include everything twice, but it
seems that including just one time is enough. Not sure what happened
when I tested it.

> It probably would be nice to have an option for "data structures, doc
> sections, and exported functions only" at some point.

Yeah. Well, actually, I ended by moving the doc sections from the
headers, adding them as a separate rst file. This way, I don't have
to workaround on some parsing issues that might happen with kernel-doc
parsing. Also, IMHO, it makes easier to edit and keep it organized.

Yet, still it could be interesting to be able of putting data structs
on a separate page than the functions. One of the (minor) issues.
What I'm noticing now is that some HTML pages are becoming too big,
as Sphinx is associating one output page per one input page.

It means that, for something like the V4L2 core:

Video2Linux devices
-------------------

.. kernel-doc:: include/media/tuner.h

.. kernel-doc:: include/media/tuner-types.h

.. kernel-doc:: include/media/tveeprom.h

.. kernel-doc:: include/media/v4l2-async.h

.. kernel-doc:: include/media/v4l2-ctrls.h

.. kernel-doc:: include/media/v4l2-dv-timings.h

.. kernel-doc:: include/media/v4l2-event.h

.. kernel-doc:: include/media/v4l2-flash-led-class.h

.. kernel-doc:: include/media/v4l2-mc.h

.. kernel-doc:: include/media/v4l2-mediabus.h

.. kernel-doc:: include/media/v4l2-mem2mem.h

.. kernel-doc:: include/media/v4l2-of.h

.. kernel-doc:: include/media/v4l2-rect.h

.. kernel-doc:: include/media/v4l2-subdev.h

.. kernel-doc:: include/media/videobuf2-core.h

.. kernel-doc:: include/media/videobuf2-v4l2.h

.. kernel-doc:: include/media/videobuf2-memops.h

It produces a 337.4KB document with 3739 lines:

  3739  24703 337487 /devel/v4l/patchwork/Documentation/output/html/media/kapi/v4l2-core.html


Btw, if you want to see how the media conversion to ReST is going,
I have it altogether at:
	https://linuxtv.org/downloads/v4l-dvb-apis-new/index.html

Almost everything is there already, including all documents that
were at Documentation/dvb, and almost all that were at
Documentation/video4linux/. There are just 30 documents left that I still
need to handle, and that requires more care to be ported:

Documentation/video4linux/
├── bttv
│   ├── Cards
│   ├── CONTRIBUTORS
│   ├── ICs
│   ├── Insmod-options
│   ├── MAKEDEV
│   ├── Modprobe.conf
│   ├── Modules.conf
│   ├── PROBLEMS
│   ├── README
│   ├── README.freeze
│   ├── README.quirks
│   ├── README.WINVIEW
│   ├── Sound-FAQ
│   ├── Specs
│   ├── THANKS
│   └── Tuners
├── cx2341x
│   ├── fw-calling.txt
│   ├── fw-decoder-api.txt
│   ├── fw-decoder-regs.txt
│   ├── fw-dma.txt
│   ├── fw-encoder-api.txt
│   ├── fw-memory.txt
│   ├── fw-osd-api.txt
│   ├── fw-upload.txt
│   ├── README.hm12
│   └── README.vbi
├── cx88
│   └── hauppauge-wintv-cx88-ir.txt
├── hauppauge-wintv-cx88-ir.txt
├── lifeview.txt
└── not-in-cx2388x-datasheet.txt

3 directories, 30 files

My plan is to handle those today, likely merging some text files
into a few ones.

I still need to do a second round of review on the kAPI book and at the
V4L and DVB drivers books, to make them to look more like a single
document, and not a "Frankenstein" glue.

Some documents are too outdated too. So, their contents need to be
adjusted. My plan is to do an extra review on that for 4.9, in
order to either update or drop them.

Thanks,
Mauro

Re: Troubles with kernel-doc and RST files

[Markus Heiser]

Am 18.07.2016 um 13:54 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:

> Em Sun, 17 Jul 2016 20:37:19 -0600
> Jonathan Corbet <corbet@lwn.net> escreveu:
> 
>> [Back home and trying to get going on stuff for real.  I'll look at the
>> issues listed in this message one at a time.]
>> 
>> On Sun, 17 Jul 2016 10:01:54 -0300
>> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
>> 
>>> 1) We now need to include each header file with documentation twice,
>>> one to get the enums, structs, typedefs, ... and another one for the
>>> functions:
>>> 
>>> 	.. kernel-doc:: include/media/media-device.h
>>> 
>>> 	.. kernel-doc:: include/media/media-entity.h
>>> 	   :export: drivers/media/media-entity.c  
>> 
>> So I'm a little confused here; you're including from two different header
>> files here.  Did you want media-entity.h in both directives?
> 
> Yeah, on my patch I was including every header twice. The first
> one to get the structs:
> 
> .. kernel-doc:: include/media/media-device.h
> 
> .. kernel-doc:: include/media/media-devnode.h
> 
> .. kernel-doc:: include/media/media-entity.h
> 
> And the next one to get the functions:
> 
> .. kernel-doc:: include/media/media-device.h
>   :export: drivers/media/media-device.c
> 
> .. kernel-doc:: include/media/media-entity.h
>   :export: drivers/media/media-entity.c
> 
> 
>> If I do a simple test with a single line:
>> 
>> 	.. kernel-doc:: include/media/media-entity.h
>> 
>> I get everything - structs, functions, etc. - as I would expect.  Are you
>> seeing something different?
> 
> Weird, now it worked... I noticed this issue because some of the cross
> references were broken if I didn't include everything twice, but it
> seems that including just one time is enough. Not sure what happened
> when I tested it.
> 
>> It probably would be nice to have an option for "data structures, doc
>> sections, and exported functions only" at some point.
> 
> Yeah. Well, actually, I ended by moving the doc sections from the
> headers, adding them as a separate rst file. This way, I don't have
> to workaround on some parsing issues that might happen with kernel-doc
> parsing. Also, IMHO, it makes easier to edit and keep it organized.

To have an option for "data structures etc." would be nice, but first
we should concentrate on the reST produced by kernel-doc and therefor
it is recommended to elaborate what we need to build man pages.
The man pages request will reveal what need e.g:

* using the cpp domain to handle more then one e.g. "ioctl" declaration
* structured markup with headers
* quoting pointers
* ...

IMHO yet, the main drawback of the current kernel-doc parser is, that
there are no header structures in the reST markup. E.g. the example
from Mauro (see below) is one big HTML page with no chapters and sections,
thats why there are no links generated in the left navigation bar.

These -- and the other request we discussed -- could be done with the
kernel-doc perl script, but we will see that it becomes harder
and harder to force it through a pipe communication.

I wrote a python version of the parser with an API which could cover all
theses and future aspects less complicated and more straight forward.
I tested this parser by building a complete source tree of documentation:

  http://return42.github.io/sphkerneldoc/linux_src_doc/index.html

and all books (aka DocBooks)

  http://return42.github.io/sphkerneldoc/#references-to-books

I recommend to consider to switch to the python version of the parser.
I know, that there is a natural shyness about a reimplementation in python
and thats why I offer to support it for a long time period .. it would
be a joy for me ;-)

If you interested in, I could send a RFC patch for this, if not please
give the reasons why not.


> Yet, still it could be interesting to be able of putting data structs
> on a separate page than the functions. One of the (minor) issues.
> What I'm noticing now is that some HTML pages are becoming too big,
> as Sphinx is associating one output page per one input page.

Yes, that is right. Changing this 1:1 associations could be done 
by feature the kernel-doc directive. But a can't recommend this, since
this breaks some basic rules sphinx implementations expect.

I recommend to split the kernel-doc directives into separate rst-files.

Over all: IMHO "Explicit is better than implicit." ... its is better to
name each function, struct etc. e.g: 

.. kernel-doc:: include/media/tuner.h
    :functions: tuner_mode

Being explicit gives the parser the chance to log errors if a
declaration not or no longer exists.

Yes, I know there are use cases which will be covered better
by being implicit ... the decision is left to the author.


> It means that, for something like the V4L2 core:
> 
> Video2Linux devices
> -------------------
> 
> .. kernel-doc:: include/media/tuner.h
> 
> .. kernel-doc:: include/media/tuner-types.h
> 
> .. kernel-doc:: include/media/tveeprom.h
> 
> .. kernel-doc:: include/media/v4l2-async.h
> 
> .. kernel-doc:: include/media/v4l2-ctrls.h
> 
> .. kernel-doc:: include/media/v4l2-dv-timings.h
> 
> .. kernel-doc:: include/media/v4l2-event.h
> 
> .. kernel-doc:: include/media/v4l2-flash-led-class.h
> 
> .. kernel-doc:: include/media/v4l2-mc.h
> 
> .. kernel-doc:: include/media/v4l2-mediabus.h
> 
> .. kernel-doc:: include/media/v4l2-mem2mem.h
> 
> .. kernel-doc:: include/media/v4l2-of.h
> 
> .. kernel-doc:: include/media/v4l2-rect.h
> 
> .. kernel-doc:: include/media/v4l2-subdev.h
> 
> .. kernel-doc:: include/media/videobuf2-core.h
> 
> .. kernel-doc:: include/media/videobuf2-v4l2.h
> 
> .. kernel-doc:: include/media/videobuf2-memops.h
> 
> It produces a 337.4KB document with 3739 lines:
> 
>  3739  24703 337487 /devel/v4l/patchwork/Documentation/output/html/media/kapi/v4l2-core.html
> 
> 
> Btw, if you want to see how the media conversion to ReST is going,
> I have it altogether at:
> 	https://linuxtv.org/downloads/v4l-dvb-apis-new/index.html
> 
> Almost everything is there already, including all documents that
> were at Documentation/dvb, and almost all that were at
> Documentation/video4linux/. There are just 30 documents left that I still
> need to handle, and that requires more care to be ported:
> 
> Documentation/video4linux/
> ├── bttv
> │   ├── Cards
> │   ├── CONTRIBUTORS
> │   ├── ICs
> │   ├── Insmod-options
> │   ├── MAKEDEV
> │   ├── Modprobe.conf
> │   ├── Modules.conf
> │   ├── PROBLEMS
> │   ├── README
> │   ├── README.freeze
> │   ├── README.quirks
> │   ├── README.WINVIEW
> │   ├── Sound-FAQ
> │   ├── Specs
> │   ├── THANKS
> │   └── Tuners
> ├── cx2341x
> │   ├── fw-calling.txt
> │   ├── fw-decoder-api.txt
> │   ├── fw-decoder-regs.txt
> │   ├── fw-dma.txt
> │   ├── fw-encoder-api.txt
> │   ├── fw-memory.txt
> │   ├── fw-osd-api.txt
> │   ├── fw-upload.txt
> │   ├── README.hm12
> │   └── README.vbi
> ├── cx88
> │   └── hauppauge-wintv-cx88-ir.txt
> ├── hauppauge-wintv-cx88-ir.txt
> ├── lifeview.txt
> └── not-in-cx2388x-datasheet.txt
> 
> 3 directories, 30 files
> 
> My plan is to handle those today, likely merging some text files
> into a few ones.
> 
> I still need to do a second round of review on the kAPI book and at the
> V4L and DVB drivers books, to make them to look more like a single
> document, and not a "Frankenstein" glue.

:-)

> Some documents are too outdated too. So, their contents need to be
> adjusted. My plan is to do an extra review on that for 4.9, in
> order to either update or drop them.
> 
> Thanks,
> Mauro
> --
> To unsubscribe from this list: send the line "unsubscribe linux-media" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Troubles with kernel-doc and RST files

[Jonathan Corbet]

On Tue, 19 Jul 2016 12:00:24 +0200
Markus Heiser <markus.heiser@darmarit.de> wrote:

> I recommend to consider to switch to the python version of the parser.
> I know, that there is a natural shyness about a reimplementation in python
> and thats why I offer to support it for a long time period .. it would
> be a joy for me ;-)
> 
> If you interested in, I could send a RFC patch for this, if not please
> give the reasons why not.

We've had this discussion already...  The problem is not with "python",
it's with "reimplementation".  We have enough moving parts in this
transition already; tossing in a wholesale replacement of a tool that,
for all of its many faults, embodies a couple decades worth of experience
just doesn't seem like the right thing to do at this time.

I will be happy to entertain the idea of a new kernel-doc in the future;
trust me, I have no emotional attachment to the current one.  But please
let's solidify what we have now first.  There's enough stuff to deal with
as it is.

Thanks,

jon

Re: Troubles with kernel-doc and RST files

[Jonathan Corbet]

On Sun, 17 Jul 2016 10:01:54 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

> 2) For functions, kernel-doc is now an all or nothing. If not all
> functions are declared, it outputs this warning:
> 
> 	./include/media/media-devnode.h:1: warning: no structured comments
> 
> And give up. No functions are exported, nor it points where it bailed.
> So, we need to manually look into all exported symbols to identify
> what's missing

So could you describe this one in a bit more detail?  An example of a
file with the problem and associated kernel-doc directive would be most
helpful here.  This sounds like something we definitely want to fix.

Thanks,

jon

Re: Troubles with kernel-doc and RST files

[Jonathan Corbet]

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.

jon

Re: Troubles with kernel-doc and RST files

[Jonathan Corbet]

On Sun, 17 Jul 2016 10:01:54 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

> 4) There are now several errors when parsing functions. Those seems to
> happen when an argument is a function pointer, like:
> 
> /devel/v4l/patchwork/Documentation/media/kapi/v4l2-core.rst:757: WARNING: Error when parsing function declaration.
> If the function has no return type:
>   Error in declarator or parameters and qualifiers
>   Invalid definition: Expected identifier in nested name, got keyword: int [error at 3]
>     int v4l2_ctrl_add_handler (struct v4l2_ctrl_handler * hdl, struct v4l2_ctrl_handler * add, bool (*filter) (const struct v4l2_ctrl *ctrl)
>     ---^

So I've been trying to reproduce this one, without success; it seems to
work for me.  As it should; the parsing code really should not have
changed at all.  Is there some particular context in which this happens
for you?

Thanks,

jon

Re: Troubles with kernel-doc and RST files

[Mauro Carvalho Chehab]

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

> On Sun, 17 Jul 2016 10:01:54 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > 2) For functions, kernel-doc is now an all or nothing. If not all
> > functions are declared, it outputs this warning:
> > 
> > 	./include/media/media-devnode.h:1: warning: no structured comments
> > 
> > And give up. No functions are exported, nor it points where it bailed.
> > So, we need to manually look into all exported symbols to identify
> > what's missing  
> 
> So could you describe this one in a bit more detail?  An example of a
> file with the problem and associated kernel-doc directive would be most
> helpful here.  This sounds like something we definitely want to fix.

I actually noticed it when I was checking for the documentation generated
by the RC header file. There, I had to add documentation for several
functions:
	https://git.linuxtv.org/media_tree.git/commit/?h=docs-next&id=5b6137dc84f627e8497e554890ae02378c54f9f0

Without that, I had an error like the above, and no functions were
documented.

I didn't further tried to investigate the root cause.

One thing I noticed is that Sphinx is very poor on detecting some types
of changes, and we need to wipe out the Sphinx docs after some changes, 
as otherwise the document won't be ok. Maybe that's the case.

Another possibility is that the all or nothing behavior happens when
the :export: attribute is used.


Thanks,
Mauro

Re: Troubles with kernel-doc and RST files

[Mauro Carvalho Chehab]

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

Re: Troubles with kernel-doc and RST files

[Mauro Carvalho Chehab]

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

> On Sun, 17 Jul 2016 10:01:54 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > 4) There are now several errors when parsing functions. Those seems to
> > happen when an argument is a function pointer, like:
> > 
> > /devel/v4l/patchwork/Documentation/media/kapi/v4l2-core.rst:757: WARNING: Error when parsing function declaration.
> > If the function has no return type:
> >   Error in declarator or parameters and qualifiers
> >   Invalid definition: Expected identifier in nested name, got keyword: int [error at 3]
> >     int v4l2_ctrl_add_handler (struct v4l2_ctrl_handler * hdl, struct v4l2_ctrl_handler * add, bool (*filter) (const struct v4l2_ctrl *ctrl)
> >     ---^  
> 
> So I've been trying to reproduce this one, without success; it seems to
> work for me.  As it should; the parsing code really should not have
> changed at all.  Is there some particular context in which this happens
> for you?

You could pull from my tree and see it yourself:
	git://linuxtv.org/media_tree.git docs-next

What I'm noticing is a series of problems when parsing some
function declarations. The number of warnings varies, depending
on the Sphinx version.

Basically, on all versions, it doesn't recognize arguments like:
	bool (*filter) (const struct v4l2_ctrl *ctrl)

(this comes from kernel-doc)

Sphinx itself doesn't even recognize arguments with "enum"
on versions 1.3.x or older. With enums, it will still add it to
the book. Just the cross-reference at the index won't appear.


Thanks,
Mauro

Re: Troubles with kernel-doc and RST files

[Markus Heiser]

Am 20.07.2016 um 00:58 schrieb Jonathan Corbet <corbet@lwn.net>:

> On Tue, 19 Jul 2016 12:00:24 +0200
> Markus Heiser <markus.heiser@darmarit.de> wrote:
> 
>> I recommend to consider to switch to the python version of the parser.
>> I know, that there is a natural shyness about a reimplementation in python
>> and thats why I offer to support it for a long time period .. it would
>> be a joy for me ;-)
>> 
>> If you interested in, I could send a RFC patch for this, if not please
>> give the reasons why not.
> 
> We've had this discussion already...

Hi Jon,

for me -- and may be I'am forgetful -- it was not really clear in 
the past discussion .. anyway I would say; thanks for clarifying  
your POV .. 

>  The problem is not with "python",
> it's with "reimplementation".  We have enough moving parts in this
> transition already; tossing in a wholesale replacement of a tool that,
> for all of its many faults, embodies a couple decades worth of experience
> just doesn't seem like the right thing to do at this time.
> 
> I will be happy to entertain the idea of a new kernel-doc in the future;
> trust me, I have no emotional attachment to the current one.  But please
> let's solidify what we have now first.  There's enough stuff to deal with
> as it is.

OK, now I will accept to stay with the perl one and for this I will send
my next patches ...

Thanks

  -- Markus --

Re: Troubles with kernel-doc and RST files

[Markus Heiser]

Am 20.07.2016 um 02:09 schrieb 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.

I'am not sure, but this might be due to the ".. kernel-doc::" directive.
Give me some time to dig.

-- Markus --

> 
> 
> Thanks,
> Mauro