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

Daniel Vetter daniel at ffwll.ch
Tue Dec 8 02:14:16 PST 2015

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 Vetter
Software Engineer, Intel Corporation

More information about the Intel-gfx mailing list