Troubles with kernel-doc and RST files
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
[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.]
Quoted 8 lines · On Sun, 17 Jul 2016 10:01:54 -0300 Mauro Carvalho Chehab…
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
Em Sun, 17 Jul 2016 20:37:19 -0600
Jonathan Corbet <[email protected]> escreveu:
Quoted 10 lines
[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.]
Quoted 4 lines · On Sun, 17 Jul 2016 10:01:54 -0300 Mauro Carvalho Chehab…
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:
Quoted 7 lines
Quoted 4 lines
.. kernel-doc::
include/media/media-device.h.. kernel-doc::
include/media/media-entity.h
:export:drivers/media/media-entity.cSo I'm a little confused here; you're including from two different header files here. Did you want
media-entity.hin 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
Quoted 6 lines
If I do a simple test with a single line:
.. kernel-doc::
include/media/media-entity.hI 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.
Quoted 2 lines
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
Am 18.07.2016 um 13:54 schrieb Mauro Carvalho Chehab <[email protected]>:
Quoted 51 lines
Em Sun, 17 Jul 2016 20:37:19 -0600
Jonathan Corbet <[email protected]> escreveu:Quoted 10 lines
[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.]
Quoted 4 lines · On Sun, 17 Jul 2016 10:01:54 -0300 Mauro Carvalho Chehab…
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:
Quoted 7 lines
Quoted 4 lines
.. kernel-doc::
include/media/media-device.h.. kernel-doc::
include/media/media-entity.h
:export:drivers/media/media-entity.cSo I'm a little confused here; you're including from two different header files here. Did you want
media-entity.hin 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.hAnd 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.cQuoted 6 lines
If I do a simple test with a single line:
.. kernel-doc::
include/media/media-entity.hI 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.
Quoted 7 lines
Quoted 2 lines
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.
Quoted 4 lines
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.
Quoted 88 lines
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.hIt 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.htmlAlmost everything is there already, including all documents that were at
Documentation/dvb, and almost all that were atDocumentation/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
Quoted 8 lines
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.
:-)
Quoted 10 lines
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 [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Quoted 7 lines · On Tue, 19 Jul 2016 12:00:24 +0200 Markus Heiser <[email protected]>…
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
Am 20.07.2016 um 00:58 schrieb Jonathan Corbet <[email protected]>:
Quoted 8 lines
Quoted 5 lines · On Tue, 19 Jul 2016 12:00:24 +0200 Markus Heiser <[email protected]>…
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 ;-)
Quoted 4 lines
Quoted 2 lines
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 ..
Quoted 10 lines
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 --
Quoted 8 lines · On Sun, 17 Jul 2016 10:01:54 -0300 Mauro Carvalho Chehab…
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 commentsAnd 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
Em Tue, 19 Jul 2016 17:01:33 -0600
Jonathan Corbet <[email protected]> escreveu:
Quoted 8 lines
Quoted 5 lines · On Sun, 17 Jul 2016 10:01:54 -0300 Mauro Carvalho Chehab…
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
Quoted 7 lines
Quoted 3 lines
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
Quoted 6 lines · On Sun, 17 Jul 2016 10:01:54 -0300 Mauro Carvalho Chehab…
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.
Quoted 6 lines
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.rsthas 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
Em Tue, 19 Jul 2016 17:16:35 -0600
Jonathan Corbet <[email protected]> escreveu:
Quoted 16 lines
Quoted 6 lines · On Sun, 17 Jul 2016 10:01:54 -0300 Mauro Carvalho Chehab…
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.Quoted 6 lines
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.rsthas only 260 lines at the time I got such error.
Quoted 7 lines
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
Am 20.07.2016 um 02:09 schrieb Mauro Carvalho Chehab <[email protected]>:
Quoted 22 lines
Em Tue, 19 Jul 2016 17:16:35 -0600
Jonathan Corbet <[email protected]> escreveu:Quoted 19 lines
Quoted 6 lines · On Sun, 17 Jul 2016 10:01:54 -0300 Mauro Carvalho Chehab…
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.Quoted 6 lines
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.rsthas 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.
Quoted 8 lines
Quoted 4 lines
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 --
Quoted 4 lines
Thanks,
Mauro
Quoted 9 lines · On Sun, 17 Jul 2016 10:01:54 -0300 Mauro Carvalho Chehab…
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]
intv4l2_ctrl_add_handler(structv4l2_ctrl_handler* hdl, structv4l2_ctrl_handler* add, bool (*filter) (const structv4l2_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
Em Tue, 19 Jul 2016 17:30:24 -0600
Jonathan Corbet <[email protected]> escreveu:
Quoted 13 lines
Quoted 9 lines · On Sun, 17 Jul 2016 10:01:54 -0300 Mauro Carvalho Chehab…
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]
intv4l2_ctrl_add_handler(structv4l2_ctrl_handler* hdl, structv4l2_ctrl_handler* add, bool (*filter) (const structv4l2_ctrl*ctrl) ---^
Quoted 4 lines
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