RFC? [PATCH] docs-rst: kernel-doc: better output struct members
From: Markus Heiser <hidden>
Date: 2016-08-22 08:56:47
Am 21.08.2016 um 14:11 schrieb Mauro Carvalho Chehab [off-list ref]:
Right now, for a struct, kernel-doc produces the following output:
.. c:type:: struct v4l2_prio_state
stores the priority states
**Definition**
::
struct v4l2_prio_state {
atomic_t prios[4];
};
**Members**
``atomic_t prios[4]``
array with elements to store the array priorities
Putting a member name in verbatim and adding a continuation line
causes the LaTeX output to generate something like:
item[atomic_t prios\[4\]] array with elements to store the array prioritiesRight now, the description of C-struct members is a simple rest-definition-list (not in the c-domain). It might be better to use the c-domain for members: http://www.sphinx-doc.org/en/stable/domains.html#directive-c:member But this is not the only thing we have to consider. To make a valid C-struct description (with targets/references in the c-domain) we need a more *structured* reST markup where the members are described in the block-content of the struct directive. E.g: <SNIP> ----------- |.. c:type:: struct v4l2_subdev_ir_ops | | operations for IR subdevices | | .. c:member:: int (* rx_read) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num) | <SNIP> ----------- By this small example, you see, that we have to discuss the whole markup produced by the kernel-doc script (function arguments, unions etc.). IMHO, since kernel-doc is widely used, this should be a RFC. -- Markus --
quoted hunk ↗ jump to hunk
Everything inside "item" is non-breakable, with may produce lines bigger than the column width. Also, for function members, like: int (* rx_read) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num); It puts the name of the member at the end, like: int (*) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num) read With is very confusing. The best is to highlight what really matters: the member name; the type is a secondary information. So, change kernel-doc, for it to produce the output on a different way: **Members** ``prios[4]`` - **type**: ``atomic_t`` array with elements to store the array priorities With such change, the name of the member will be the first visible thing, and will be in bold style. The type will still be there, inside a list. Also, as the type is not part of LaTeX "item[]", LaTeX will split it into multiple lines, if needed. So, both LaTeX/PDF and HTML outputs will look good. It should be noticed, however, that the way Sphinx LaTeX output handles things like: Foo bar is different than the HTML output. On HTML, it will produce something like: **Foo** bar While, on LaTeX, it puts both foo and bar at the same line, like: **Foo** bar By starting the second line with a dash, both HTML and LaTeX output will do the same thing. Signed-off-by: Mauro Carvalho Chehab <redacted> --- scripts/kernel-doc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)diff --git a/scripts/kernel-doc b/scripts/kernel-doc index ba081c7636a2..78e355281e1a 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc@@ -2000,7 +2000,8 @@ sub output_struct_rst(%) {($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; $type = $args{'parametertypes'}{$parameter}; print_lineno($parameterdesc_start_lines{$parameter_name}); - print "``$type $parameter``\n"; + print "``" . $parameter . "``\n"; + print " - **type**: ``$type``\n\n"; output_highlight_rst($args{'parameterdescs'}{$parameter_name}); print "\n"; } -- 2.7.4 -- 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