Re: RFC? [PATCH] docs-rst: kernel-doc: better output struct members

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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



[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux