[PATCH 7/8] drm/doc: fix drm_plane_type docs

[Simon Ser]

On Thursday, December 17th, 2020 at 11:50 AM, Daniel Vetter <daniel at ffwll.ch> wrote:

> > > > @@ -557,19 +561,20 @@ enum drm_plane_type {
> > > >     /**
> > > >      * @DRM_PLANE_TYPE_PRIMARY:
> > > >      *
> > > > -    * Primary planes represent a "main" plane for a CRTC.  Primary planes
> > > > -    * are the planes operated upon by CRTC modesetting and flipping
> > > > -    * operations described in the &drm_crtc_funcs.page_flip and
> > > > -    * &drm_crtc_funcs.set_config hooks.
> > >
> > > I think we should keep the notice which legacy entry hooks implicitly
> > > operate on the primary plane. Not sure why you're removing the above
> > > sentence. Maybe improve it by adding "See also &drm_crtc.primary." for
> > > more context?
> >
> > I intentionally removed it, because setting the plane type will not magically
> > make it used for legacy IOCTLs. The previous version documented the legacy
> > IOCTLs behaviour in the primary and cursor type docs. That was misleading
> > because only the drm_crtc.{primary,cursor} pointers make it so a plane is used
> > for legacy IOCTLs, not the type.
> >
> > This patch does keep a reference to drm_crtc.{primary,cursor}, in the paragraph
> > right above. Clicking on the reference will explain in detail which legacy
> > IOCTLs are affected. I don't think repeating the paragraph again in the primary
> > and cursor type docs is necessary.
>
> Hm I guess works too, I'm not sure documentations must avoid
> repetitions at all costs (since it generally makes stuff harder to
> find, despite all the links).

I didn't find the repetition necessary because the paragraph referencing
drm_crtc.{primary,cursor} is literally just a few lines of text away. But I
guess as long as it's clear that setting the type doesn't set
drm_crtc.{primary,cursor} I'm fine with duplicating the references.