Re: [PATCH 3/7] drm/doc: Add GEM/CMA helpers to kerneldoc

From: Thierry Reding <thierry.reding@gmail.com>
To: Daniel Vetter <daniel@ffwll.ch>
Cc: Benjamin Gaignard <benjamin.gaignard@linaro.org>,
	Daniel Vetter <daniel.vetter@ffwll.ch>,
	dri-devel@lists.freedesktop.org,
	Tomi Valkeinen <tomi.valkeinen@ti.com>,
	Archit Taneja <archit@ti.com>,
	Laurent Pinchart <laurent.pinchart@ideasonboard.com>,
	Russell King <rmk+kernel@arm.linux.org.uk>,
	Dave Airlie <airlied@redhat.com>
Subject: Re: [PATCH 3/7] drm/doc: Add GEM/CMA helpers to kerneldoc
Date: Wed, 5 Nov 2014 16:16:24 +0100	[thread overview]
Message-ID: <20141105151623.GD24353@ulmo> (raw)
In-Reply-To: <20141105150455.GU26941@phenom.ffwll.local>

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

On Wed, Nov 05, 2014 at 04:04:55PM +0100, Daniel Vetter wrote:
> On Wed, Nov 05, 2014 at 04:01:26PM +0100, Thierry Reding wrote:
> > On Wed, Nov 05, 2014 at 03:34:40PM +0100, Daniel Vetter wrote:
> > > On Wed, Nov 05, 2014 at 02:25:15PM +0100, Thierry Reding wrote:
> > > > + * Return: A struct drm_gem_cma_object * on success or an ERR_PTR()-encoded
> > > 
> > > Same bikeshed about "Returns:\n" as with the panel kerneldoc patch.
> > 
> > I've been following the style described in the kernel-doc nano-HOWTO,
> > which says that:
> > 
> > 	The return value, if any, should be described in a dedicated
> > 	section named "Return".
> > 
> > There are other things in that document that we don't follow in DRM, so
> > I wonder if we should just consider it as guidelines rather than actual
> > rules (they aren't enforced anyway) or perhaps make a pass over existing
> > kerneldoc and convert it to the rules described in that document.
> > 
> > That document is the only reference for the kerneldoc syntax (that I
> > know of), so I had always thought that we should be following it.
> 
> We've started out with all-uppercase RETURNS from userspace libdrm iirc. I
> don't care really, but iirc the Returns: is the common one we use. Imo it
> also reads better in English, but not native speaker here ;-)

Alright, I'll go with the variant that you proposed for the sake of
consistency.

Thierry

[-- Attachment #1.2: 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