[PATCH v2] drm: document drm_mode_get_connector

[Daniel Vetter]

On Fri, Nov 20, 2020 at 9:46 AM Simon Ser <contact at emersion.fr> wrote:
>
> On Thursday, November 19, 2020 4:06 PM, Daniel Vetter <daniel at ffwll.ch> wrote:
>
> > > +       /**
> > > +        * @connection: Status of the connector.
> > > +        *
> > > +        * See enum drm_connector_status.
> >
> > Please add & so it becomes a link in the generated docs (and pls check
> > the link goes to the right place).
>
> Per [1], just prefixing the enum name with "enum" is enough to generate a link.
> I prefer this style over the ampersand because it makes the raw text easier to
> read. The result looks like this [2].
>
> [1]: https://dri.freedesktop.org/docs/drm/doc-guide/kernel-doc.html#cross-referencing-from-restructuredtext
> [2]: https://l.sr.ht/o7Kb.png

Ah nice, I missed that this was updated. We have a ton of & in our
kerneldoc that probably could be dropped ...
-Daniel

>
> > > +        */
> > >         __u32 connection;
> > > -       __u32 mm_width;  /**< width in millimeters */
> > > -       __u32 mm_height; /**< height in millimeters */
> > > +       /** @mm_width: Width of the connected sink in millimeters. */
> > > +       __u32 mm_width;
> > > +       /** @mm_height: Height of the connected sink in millimeters. */
> > > +       __u32 mm_height;
> > > +       /**
> > > +        * @subpixel: Subpixel order of the connected sink.
> > > +        *
> > > +        * See enum subpixel_order.
> >
> > Same here.
>
> This one doesn't generate a link, because enum subpixel_order is undocumented.
> As soon as it's documented, the link will be created.
>
> The enum is weird in the first place: it has CamelCase members and no drm_
> prefix.
>
> > With the nits addressed: Reviewed-by: Daniel Vetter <daniel.vetter at ffwll.ch>
>
> I'll fix the other issues you've raised, thanks for the review!



-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch