docs-rst: kernel-doc: better output struct members
authorMauro Carvalho Chehab <mchehab@s-opensource.com>
Tue, 23 Aug 2016 01:02:57 +0000 (22:02 -0300)
committerJonathan Corbet <corbet@lwn.net>
Wed, 24 Aug 2016 21:24:36 +0000 (15:24 -0600)
commit6d232c80158ae5a6fb497e0462d52c57c4459439
treec3b317f0aba9b77e9155eb9fcb9547c82e14f0de
parentca7bfe2c8d9f3aee469a3a36110a95ebb511ee20
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>
scripts/kernel-doc