Re: [PATCH 07/28] drm: Update drm_plane_funcs kerneldoc

From: Thierry Reding <thierry.reding@gmail.com>
To: Daniel Vetter <daniel@ffwll.ch>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>,
	Intel Graphics Development <intel-gfx@lists.freedesktop.org>,
	DRI Development <dri-devel@lists.freedesktop.org>,
	Daniel Vetter <daniel.vetter@intel.com>
Subject: Re: [PATCH 07/28] drm: Update drm_plane_funcs kerneldoc
Date: Mon, 7 Dec 2015 13:43:49 +0100	[thread overview]
Message-ID: <20151207124349.GA13177@ulmo> (raw)
In-Reply-To: <20151207123416.GF10243@phenom.ffwll.local>

[-- Attachment #1.1: Type: text/plain, Size: 1697 bytes --]

On Mon, Dec 07, 2015 at 01:34:16PM +0100, Daniel Vetter wrote:
> On Mon, Dec 07, 2015 at 12:46:38PM +0100, Thierry Reding wrote:
> > On Fri, Dec 04, 2015 at 09:45:48AM +0100, Daniel Vetter wrote:
> > > diff --git a/include/drm/drm_crtc.h b/include/drm/drm_crtc.h
> > [...]
> > > +	/**
> > > +	 * @destroy:
> > > +	 *
> > > +	 * Clean up CRTC resources. This is only called at driver unload time
> > 
> > Perhaps drop "only" because there are more than a single potential
> > usage?
> 
> It's for driver unload only since you can't hotplug planes. The only
> hotpluggable thing in drm atm are connectors, and I've added these blurbs
> to highlight that.

The complete hunk is this:

+        * Clean up CRTC resources. This is only called at driver unload time
+        * through drm_mode_config_cleanup(), but can also be called at runtime
+        * when a CRTC is being hot-unplugged.

If you say CRTCs aren't hotpluggable then the above is very confusing.
So either it is only called at driver unload time (which is what you're
saying, since CRTCs aren't hotpluggable) or it can be called in other
circumstances, in which case "only" is wrong.

So I think either drop the last subsentence to reflect the current
capabilities of the subsystem, or make it something like the following
to clarify:

	The DRM subsystem doesn't currently support hotplugging CRTCs,
	but eventually that feature might be added, at which point this
	callback will be called when a CRTC in hot-unplugged.

But since nobody knows when this will happen it's somewhat premature, in
my opinion, to have such documentation. kerneldoc should document facts,
not the roadmap.

Thierry

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

[-- Attachment #2: Type: text/plain, Size: 159 bytes --]

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