[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 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index ba081c7636a2..d225e178aa1b 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -2000,7 +2000,7 @@ 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";
 	output_highlight_rst($args{'parameterdescs'}{$parameter_name});
 	print "\n";
     }
-- 
2.7.4

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

[Mauro Carvalho Chehab]

Em Mon, 22 Aug 2016 21:41:51 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> escreveu:

> Right now, for a struct, kernel-doc produces the following output:

Please discard this one... the description is wrong.

Just sent a v2.

Thanks,
Mauro

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

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

[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