[Intel-gfx] [PATCH 1/5] [RFC] drm: Documentation style guide

[Daniel Vetter]

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