Em Mon, 22 Aug 2016 15:34:21 -0600
Jonathan Corbet <cor...@lwn.net> escreveu:
> On Sun, 21 Aug 2016 09:11:57 -0300
> Mauro Carvalho Chehab <mche...@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
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
