On Mon, 22 Aug 2016, Markus Heiser [off-list ref] wrote:

Am 22.08.2016 um 13:16 schrieb Jani Nikula [off-list ref]:

quoted

On Mon, 22 Aug 2016, Mauro Carvalho Chehab [off-list ref] wrote:

quoted

Markus,

Em Mon, 22 Aug 2016 10:56:01 +0200
Markus Heiser [off-list ref] escreveu:

quoted

Am 21.08.2016 um 14:11 schrieb Mauro Carvalho Chehab [off-list ref]:

quoted

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  

Right 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.

I tried using c:member. It won't work on LaTeX output, as it will
still put everything into a LaTeX item, with doesn't do line breaks.

I've tried c:member before, and I'm not convinced it buys us anything
useful. I'm also not convinced we'd need more structured rst markup
within struct or function descriptions in addition to what we currently
have. Keep it simple.

BR,
Jani.

It buys, that we stay in the c-domain and we can refer to the members
with the :c:member role. E.g :c:member:`v4l2_subdev_ir_ops.rx_read`.

Yes, it allows anchors to members, while detaching the member
descriptions from the struct descriptions. In the output, there is no
perceivable parent-child relationship between the struct and its
members. Arguably the resulting documentation is harder to follow with
c:member than without. I think it's sufficient to link to the struct
descriptions. It's not enough to say that theoretically using c:member
is the right thing; it needs to be better in practice too.

BR,
Jani.

-- Markus --
 

-- 
Jani Nikula, Intel Open Source Technology Center