Am 22.08.2016 um 13:52 schrieb Jani Nikula <jani.nikula@xxxxxxxxx>:
> 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.
May I misunderstood you "detaching"? .. As far as I know, the members
has to be in the (indented) block of struct description (like above).
Anyway, I realized (last mail), that the c-parser of Sphinx is totally
broken in type / name detecting from signatures, with we have no reliable
anchors and it makes no more sense to follow my first intention.
To summarize: after a few thoughts ... I agree with your KIS strategy ;-)
-- Markus --
> 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.
>
--
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
