diff options
author | Mauro Carvalho Chehab <mchehab@s-opensource.com> | 2016-08-23 04:02:57 +0300 |
---|---|---|
committer | Jonathan Corbet <corbet@lwn.net> | 2016-08-25 00:24:36 +0300 |
commit | 6d232c80158ae5a6fb497e0462d52c57c4459439 (patch) | |
tree | c3b317f0aba9b77e9155eb9fcb9547c82e14f0de /Documentation | |
parent | ca7bfe2c8d9f3aee469a3a36110a95ebb511ee20 (diff) | |
download | linux-6d232c80158ae5a6fb497e0462d52c57c4459439.tar.xz |
docs-rst: kernel-doc: better output struct members
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 priorities
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.
is a secondary information.
So, change kernel-doc, for it to produce the output on a different way:
**Members**
``prios[4]``
array with elements to store the array priorities
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
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation')
0 files changed, 0 insertions, 0 deletions