On Mon, 22 Aug 2016, Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote:
> 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`.
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
--
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
