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

[Daniel Vetter]

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 ;-)
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch