Am 22.08.2016 um 13:16 schrieb Jani Nikula <jani.nikula@xxxxxxxxx>:
> On Mon, 22 Aug 2016, Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx> wrote:
>> Markus,
>>
>> Em Mon, 22 Aug 2016 10:56:01 +0200
>> Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu:
>>
>>> Am 21.08.2016 um 14:11 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>:
>>>
>>>> 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`.
-- Markus --
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
