Em Mon, 22 Aug 2016 14:52:42 +0300
Jani Nikula <jani.nikula@xxxxxxxxx> escreveu:
> 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. 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
--
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
