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

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

[Mauro Carvalho Chehab]

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

Everything inside "item" is non-breakable, with may produce
lines bigger than the column width.

Also, for function members, like:

        int (* rx_read) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num);

It puts the name of the member at the end, like:

        int (*) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num) read

With is very confusing.

The best is to highlight what really matters: the member name; the type
is a secondary information.

So, change kernel-doc, for it to produce the output on a different way:

	**Members**

	``prios[4]``
	  - **type**: ``atomic_t``

	  array with elements to store the array priorities

With such change, the name of the member will be the first visible
thing, and will be in bold style. The type will still be there, inside
a list.

Also, as the type is not part of LaTeX "item[]", LaTeX will split it into
multiple lines, if needed.

So, both LaTeX/PDF and HTML outputs will look good.

It should be noticed, however, that the way Sphinx LaTeX output handles
things like:

	Foo
	   bar

is different than the HTML output. On HTML, it will produce something
like:

	**Foo**
	   bar

While, on LaTeX, it puts both foo and bar at the same line, like:

	**Foo** bar

By starting the second line with a dash, both HTML and LaTeX output
will do the same thing.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 scripts/kernel-doc | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index ba081c7636a2..78e355281e1a 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -2000,7 +2000,8 @@ sub output_struct_rst(%) {
 	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 	$type = $args{'parametertypes'}{$parameter};
         print_lineno($parameterdesc_start_lines{$parameter_name});
-	print "``$type $parameter``\n";
+	print "``" . $parameter . "``\n";
+	print "  - **type**: ``$type``\n\n";
 	output_highlight_rst($args{'parameterdescs'}{$parameter_name});
 	print "\n";
     }
-- 
2.7.4

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

[Markus Heiser]

Am 21.08.2016 um 14:11 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:

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

-- Markus --

> 
> Everything inside "item" is non-breakable, with may produce
> lines bigger than the column width.
> 
> Also, for function members, like:
> 
>        int (* rx_read) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num);
> 
> It puts the name of the member at the end, like:
> 
>        int (*) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num) read
> 
> With is very confusing.
> 
> The best is to highlight what really matters: the member name; the type
> is a secondary information.
> 
> So, change kernel-doc, for it to produce the output on a different way:
> 
> 	**Members**
> 
> 	``prios[4]``
> 	  - **type**: ``atomic_t``
> 
> 	  array with elements to store the array priorities
> 
> With such change, the name of the member will be the first visible
> thing, and will be in bold style. The type will still be there, inside
> a list.
> 
> Also, as the type is not part of LaTeX "item[]", LaTeX will split it into
> multiple lines, if needed.
> 
> So, both LaTeX/PDF and HTML outputs will look good.
> 
> It should be noticed, however, that the way Sphinx LaTeX output handles
> things like:
> 
> 	Foo
> 	   bar
> 
> is different than the HTML output. On HTML, it will produce something
> like:
> 
> 	**Foo**
> 	   bar
> 
> While, on LaTeX, it puts both foo and bar at the same line, like:
> 
> 	**Foo** bar
> 
> By starting the second line with a dash, both HTML and LaTeX output
> will do the same thing.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
> scripts/kernel-doc | 3 ++-
> 1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index ba081c7636a2..78e355281e1a 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -2000,7 +2000,8 @@ sub output_struct_rst(%) {
> 	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
> 	$type = $args{'parametertypes'}{$parameter};
>         print_lineno($parameterdesc_start_lines{$parameter_name});
> -	print "``$type $parameter``\n";
> +	print "``" . $parameter . "``\n";
> +	print "  - **type**: ``$type``\n\n";
> 	output_highlight_rst($args{'parameterdescs'}{$parameter_name});
> 	print "\n";
>     }
> -- 
> 2.7.4
> 
> 
> --
> To unsubscribe from this list: send the line "unsubscribe linux-media" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Mauro Carvalho Chehab]

Markus,

Em Mon, 22 Aug 2016 10:56:01 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> Am 21.08.2016 um 14:11 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> 
> > 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.

Also, according to Sphinx manual at http://www.sphinx-doc.org/en/stable/domains.html
The syntax is:

	.. c:member:: type name

	    Describes a C struct member. Example signature:

		.. c:member:: PyObject* PyTypeObject.tp_bases

So, it expects <type> <member> as arguments. If the manual is right, it
would be expecting, instead, the weird syntax:

   .. c:member::  int (*) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num) rx_read

With hurts my eyes.

As I guess we don't want to maintain ourselves a LaTeX output Sphinx
plugin forked from upstream, I guess that a more definitive solution
would involve overriding  the parser for c:member in a way that it would
produce an output like the one in this path, while creating the proper
c domain reference for the structure member inside the C domain.

Regards,
Mauro

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

[Jani Nikula]

On Mon, 22 Aug 2016, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> Markus,
>
> Em Mon, 22 Aug 2016 10:56:01 +0200
> Markus Heiser <markus.heiser@darmarit.de> escreveu:
>
>> Am 21.08.2016 um 14:11 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
>> 
>> > 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.


>
> Also, according to Sphinx manual at http://www.sphinx-doc.org/en/stable/domains.html
> The syntax is:
>
> 	.. c:member:: type name
>
> 	    Describes a C struct member. Example signature:
>
> 		.. c:member:: PyObject* PyTypeObject.tp_bases
>
> So, it expects <type> <member> as arguments. If the manual is right, it
> would be expecting, instead, the weird syntax:
>
>    .. c:member::  int (*) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num) rx_read
>
> With hurts my eyes.
>
> As I guess we don't want to maintain ourselves a LaTeX output Sphinx
> plugin forked from upstream, I guess that a more definitive solution
> would involve overriding  the parser for c:member in a way that it would
> produce an output like the one in this path, while creating the proper
> c domain reference for the structure member inside the C domain.
>
> Regards,
> Mauro

-- 
Jani Nikula, Intel Open Source Technology Center

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

[Markus Heiser]

Am 22.08.2016 um 13:16 schrieb Jani Nikula <jani.nikula@intel.com>:

> On Mon, 22 Aug 2016, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
>> Markus,
>> 
>> Em Mon, 22 Aug 2016 10:56:01 +0200
>> Markus Heiser <markus.heiser@darmarit.de> escreveu:
>> 
>>> Am 21.08.2016 um 14:11 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
>>> 
>>>> 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 --
 

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

[Jani Nikula]

On Mon, 22 Aug 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
> Am 22.08.2016 um 13:16 schrieb Jani Nikula <jani.nikula@intel.com>:
>
>> On Mon, 22 Aug 2016, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
>>> Markus,
>>> 
>>> Em Mon, 22 Aug 2016 10:56:01 +0200
>>> Markus Heiser <markus.heiser@darmarit.de> escreveu:
>>> 
>>>> Am 21.08.2016 um 14:11 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
>>>> 
>>>>> 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

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

[Mauro Carvalho Chehab]

Em Mon, 22 Aug 2016 14:52:42 +0300
Jani Nikula <jani.nikula@intel.com> escreveu:

> On Mon, 22 Aug 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
> > Am 22.08.2016 um 13:16 schrieb Jani Nikula <jani.nikula@intel.com>:
> >  
> >> On Mon, 22 Aug 2016, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:  
> >>> Markus,
> >>> 
> >>> Em Mon, 22 Aug 2016 10:56:01 +0200
> >>> Markus Heiser <markus.heiser@darmarit.de> escreveu:
> >>>   
> >>>> Am 21.08.2016 um 14:11 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> >>>>   
> >>>>> 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.

Linking to the member is interesting, specially when describing too
big structures, like the callback ones, specially when we have the
descriptions for such things at the rst file (like we have on media kAPI
book). However, the way Sphinx outputs a :c:member: is not nice, IMHO.

I'd say that we should only use .. c:member:: if we can override its behavior
via the C domain extension in a way that it will create a C-domain
reference, but keep producing an output like:

	*member_name*
		type
		some description

on all output formats without any fancy colored struct-like style.

Also, IMHO, it should not add any entry to the genindex, to avoid
polluting it with thousands entries.

If such thing can't be done, let's just stick to what we have right now,
after this patch.


Thanks,
Mauro

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

[Markus Heiser]

Am 22.08.2016 um 14:15 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:

> Em Mon, 22 Aug 2016 14:52:42 +0300
> Jani Nikula <jani.nikula@intel.com> escreveu:
> 
>> On Mon, 22 Aug 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
>>> Am 22.08.2016 um 13:16 schrieb Jani Nikula <jani.nikula@intel.com>:
>>> 
>>>> On Mon, 22 Aug 2016, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:  
>>>>> Markus,
>>>>> 
>>>>> Em Mon, 22 Aug 2016 10:56:01 +0200
>>>>> Markus Heiser <markus.heiser@darmarit.de> escreveu:
>>>>> 
>>>>>> Am 21.08.2016 um 14:11 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
>>>>>> 
>>>>>>> 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.
> 
> Linking to the member is interesting, specially when describing too
> big structures, like the callback ones, specially when we have the
> descriptions for such things at the rst file (like we have on media kAPI
> book). However, the way Sphinx outputs a :c:member: is not nice, IMHO.
> 
> I'd say that we should only use .. c:member:: if we can override its behavior
> via the C domain extension in a way that it will create a C-domain
> reference, but keep producing an output like:
> 
> 	*member_name*
> 		type
> 		some description

The output is (nearly) independent from the way the reST is parsed.
Normally this should be realized in the builder. But we wan't
touch the latex builder and as I said, the name/type detection 
of the c-parser is broken and I don't want to implement a third
c-parser in our toolchain. 

May it is more simple to refer only the structure, even if 
the struct is big.

-- Markus --

> on all output formats without any fancy colored struct-like style.
> 
> Also, IMHO, it should not add any entry to the genindex, to avoid
> polluting it with thousands entries.
> 
> If such thing can't be done, let's just stick to what we have right now,
> after this patch.
> 
> 
> Thanks,
> Mauro

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

[Markus Heiser]

Am 22.08.2016 um 13:52 schrieb Jani Nikula <jani.nikula@intel.com>:

> On Mon, 22 Aug 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
>> Am 22.08.2016 um 13:16 schrieb Jani Nikula <jani.nikula@intel.com>:
>> 
>>> On Mon, 22 Aug 2016, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
>>>> Markus,
>>>> 
>>>> Em Mon, 22 Aug 2016 10:56:01 +0200
>>>> Markus Heiser <markus.heiser@darmarit.de> escreveu:
>>>> 
>>>>> Am 21.08.2016 um 14:11 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
>>>>> 
>>>>>> 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.
> 

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

[Markus Heiser]

Am 22.08.2016 um 12:06 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:

> Markus,
> 
> Em Mon, 22 Aug 2016 10:56:01 +0200
> Markus Heiser <markus.heiser@darmarit.de> escreveu:
> 
>> Am 21.08.2016 um 14:11 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
>> 
>>> 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.
> 
> Also, according to Sphinx manual at http://www.sphinx-doc.org/en/stable/domains.html
> The syntax is:
> 
> 	.. c:member:: type name
> 
> 	    Describes a C struct member. Example signature:
> 
> 		.. c:member:: PyObject* PyTypeObject.tp_bases
> 
> So, it expects <type> <member> as arguments. If the manual is right, it
> would be expecting, instead, the weird syntax:
> 
>   .. c:member::  int (*) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num) rx_read
> 
> With hurts my eyes.

Argh, you are right ... but it is very confusing. I made a small test::


<SNIP> ------------

.. c:type:: struct v4l2_subdev_ir_ops_001

   .. c:member::  int (*) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num) rx_read

      lorem ipsum


.. c:type:: struct v4l2_subdev_ir_ops_002

   operations for IR subdevices

   .. c:member::  int (* rx_read) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num)

      lorem ipsum


Test refs
=========

* :c:member:`v4l2_subdev_ir_ops_001.rx_read`
* :c:member:`v4l2_subdev_ir_ops_002.rx_read`

<SNIP> ------------


It seems, the c-parser is very dump, the v4l2_subdev_ir_ops_002.rx_read link
is closed, the 001 not ... a look at the sources:

* reg-exprs: https://github.com/sphinx-doc/sphinx/blob/master/sphinx/domains/c.py#L29

And the following snippet is all about handling signatures (of func, type, member .. directives)

m = c_funcptr_sig_re.match(sig)
if m is None:
    m = c_sig_re.match(sig)
if m is None:
    raise ValueError('no match')
rettype, name, arglist, const = m.groups()

In short: since the signature parsing is such worse, we can't predict
how type and name is parsed ... argh.

> As I guess we don't want to maintain ourselves a LaTeX output Sphinx
> plugin forked from upstream,

Agree

> I guess that a more definitive solution
> would involve overriding  the parser for c:member in a way that it would
> produce an output like the one in this path, while creating the proper
> c domain reference for the structure member inside the C domain.

Summarized:

* The c-parser of the Sphinx c-domain, is worse. BTW this is the next
  c-parser implementation used in the toolchain (parse-headers, kernel-doc)
  https://www.mail-archive.com/linux-media@vger.kernel.org/msg101440.html

* Even if we use a member-directive in the block of a type directive,
  it will nod be rendered well in the latex / pdf output.

OK, with this in mind, I agree with Jani ... "keep it simple" ;-)

-- Markus --

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

[Jonathan Corbet]

On Sun, 21 Aug 2016 09:11:57 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

> So, change kernel-doc, for it to produce the output on a different way:
> 
> 	**Members**
> 
> 	``prios[4]``
> 	  - **type**: ``atomic_t``
> 
> 	  array with elements to store the array priorities
> 
> With such change, the name of the member will be the first visible
> thing, and will be in bold style. The type will still be there, inside
> a list.

OK, I'll confess to not being 100% convinced on this one.  I certainly
sympathize with the problem that drives this change, but I think the
result is a bit on the noisy and visually distracting side.  

I wonder if we might be better off to just leave the "type:" bulleted
line out entirely?  The type information already appears in the structure
listing directly above, so it's arguably redundant here.  If formatting
the type is getting in the way here, perhaps the right answer is just
"don't do that"?

jon

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

[Mauro Carvalho Chehab]

Em Mon, 22 Aug 2016 15:34:21 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Sun, 21 Aug 2016 09:11:57 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > So, change kernel-doc, for it to produce the output on a different way:
> > 
> > 	**Members**
> > 
> > 	``prios[4]``
> > 	  - **type**: ``atomic_t``
> > 
> > 	  array with elements to store the array priorities
> > 
> > With such change, the name of the member will be the first visible
> > thing, and will be in bold style. The type will still be there, inside
> > a list.  
> 
> OK, I'll confess to not being 100% convinced on this one.  I certainly
> sympathize with the problem that drives this change, but I think the
> result is a bit on the noisy and visually distracting side.  
> 
> I wonder if we might be better off to just leave the "type:" bulleted
> line out entirely?  The type information already appears in the structure
> listing directly above, so it's arguably redundant here.  If formatting
> the type is getting in the way here, perhaps the right answer is just
> "don't do that"?

I almost stripped the type on the first version of this patch, as I had
the same doubt as you ;)

I ended keeping it just because I didn't have a strong argument to
strip it.

There is another reason too... just stripping it will produce a
little difference at the output:

With HTML, the output is:

	*struct v4l2_subdev_tuner_ops*

	    Callbacks used when v4l device was opened in radio mode.

	...

	*Members*

	*s_radio*
	    callback for VIDIOC_S_RADIO ioctl handler code.
	...

On LaTeX/PDF, is displayed as:

	*struct v4l2_subdev_tuner_ops*

	    Callbacks used when v4l device was opened in radio mode.

	...

	*Members*

	*s_radio* callback for VIDIOC_S_RADIO ioctl handler code.


Anyway, I'm OK on just stripping the type. I'm sending a second version
of it.

Thanks!
Mauro