Re: [PATCH 1/5] [RFC] drm: Documentation style guide

From: Daniel Vetter <daniel@ffwll.ch>
To: Daniel Vetter <daniel.vetter@ffwll.ch>,
	DRI Development <dri-devel@lists.freedesktop.org>,
	Intel Graphics Development <intel-gfx@lists.freedesktop.org>,
	Daniel Vetter <daniel.vetter@intel.com>
Subject: Re: [PATCH 1/5] [RFC] drm: Documentation style guide
Date: Tue, 8 Dec 2015 11:14:16 +0100	[thread overview]
Message-ID: <20151208101416.GG20822@phenom.ffwll.local> (raw)
In-Reply-To: <20151208095905.GA5523@Sovereign.cs.lth.se>

On Tue, Dec 08, 2015 at 10:59:05AM +0100, Pierre Moreau wrote:
> On 09:49 AM - Dec 08 2015, Daniel Vetter wrote:
> > +    <para>
> > +      Functions which have a non-<code>void</code> return value should have a
> > +      section called "Returns" explaining the expected return values in
> > +      different cases an their meanings. Currently there's no consensus whether
> > +      that section name should be all upper-case or not, and whether it should
> > +      end in a colon or not. Go with the file-local style. Other common section
> > +      names are "Notes" with information for dangerous or tricky corner cases,
> > +      and "FIXME" where the interface could be cleaned up.
> 
> Why not define (and use) a single style for naming all sections? Old
> documentation might not use it, but it should be doable to upgrade those old
> documents.

There is a massive pile of these docs, and there is a slight difference in
how vfunc table section headings and function reference section headings
are rendered. Given that I figured I'll start modestly.

But if you feel like making this consistent I'd definitely take a patch to
do so. Same really for any of the other style guideline issues. Well,
after we have some acks on this, and any large-scale style change should
first do the RFC patch for this section for discussion to avoid the risk
of wasting lots of time.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx