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

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

 



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

> On Sun, 21 Aug 2016 09:11:57 -0300
> Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx> 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
--
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