All of lore.kernel.org
 help / color / mirror / Atom feed
From: Simon Ser <contact@emersion.fr>
To: Daniel Vetter <daniel@ffwll.ch>
Cc: dri-devel <dri-devel@lists.freedesktop.org>
Subject: Re: [PATCH 7/8] drm/doc: fix drm_plane_type docs
Date: Thu, 17 Dec 2020 11:07:46 +0000	[thread overview]
Message-ID: <UVB73W4L-xIbtb-vVoHuKhzQb-EcSv0_JxZS2hyWoPNfr1NLbWbxPqZbMlAtj73nnb0GsJUlkIxRMP6oXNQyvB1BInEXqgGjGDj2lY7uo6Q=@emersion.fr> (raw)
In-Reply-To: <CAKMK7uE=oNuyaACKD1H+e5BGyGi8UZYhhgSGF=cZaB60NWNuaA@mail.gmail.com>

On Thursday, December 17th, 2020 at 11:50 AM, Daniel Vetter <daniel@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.

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

  reply	other threads:[~2020-12-17 11:07 UTC|newest]

Thread overview: 20+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-12-16 20:22 [PATCH 0/8] drm/doc: improve plane property docs Simon Ser
2020-12-16 20:22 ` [PATCH 1/8] drm/doc: rename FB_DAMAGE_CLIPS section Simon Ser
2020-12-16 20:22 ` [PATCH 2/8] drm/doc: move composition function docs to new section Simon Ser
2020-12-16 20:22 ` [PATCH 3/8] drm/doc: move damage tracking functions " Simon Ser
2020-12-16 20:22 ` [PATCH 4/8] drm/doc: move color management functions under CRTC section Simon Ser
2020-12-16 21:14   ` Daniel Vetter
2020-12-16 20:22 ` [PATCH 5/8] drm/doc: the KMS properties section is for user-space devs Simon Ser
2020-12-16 21:14   ` Daniel Vetter
2020-12-16 20:22 ` [PATCH 6/8] drm/doc: introduce new section for standard plane properties Simon Ser
2020-12-16 21:19   ` Daniel Vetter
2020-12-16 20:22 ` [PATCH 7/8] drm/doc: fix drm_plane_type docs Simon Ser
2020-12-16 21:19   ` Daniel Vetter
2020-12-17 10:37     ` Simon Ser
2020-12-17 10:50       ` Daniel Vetter
2020-12-17 11:07         ` Simon Ser [this message]
2020-12-16 20:22 ` [PATCH 8/8] drm/doc: document the type plane property Simon Ser
2020-12-16 21:23   ` Daniel Vetter
2020-12-17 10:40     ` Simon Ser
2020-12-17 10:52       ` Daniel Vetter
2020-12-17 11:09         ` Simon Ser

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to='UVB73W4L-xIbtb-vVoHuKhzQb-EcSv0_JxZS2hyWoPNfr1NLbWbxPqZbMlAtj73nnb0GsJUlkIxRMP6oXNQyvB1BInEXqgGjGDj2lY7uo6Q=@emersion.fr' \
    --to=contact@emersion.fr \
    --cc=daniel@ffwll.ch \
    --cc=dri-devel@lists.freedesktop.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body. 
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.