[PATCH] drm: Documentation style guide

[Daniel Vetter]

On Wed, Dec 09, 2015 at 01:21:09PM +0200, Jani Nikula wrote:
> On Wed, 09 Dec 2015, Daniel Vetter <daniel.vetter at ffwll.ch> wrote:
> > Every time I type or review docs this seems a bit different. Try to
> > document the common style so we can try to unify at least new docs.
> >
> > v2: Spelling fixes from Pierre, Laurent and Jani.
> 
> Nah, you ignored my comment about "these documentations use American
> English". :/

Well I did type them all in, but totally failed to run git add before
hitting send. Fixed now.
-Daniel

> 
> BR,
> Jani.
> 
> >
> > Cc: Pierre Moreau <pierre.morrow at free.fr>
> > Cc: Jani Nikula <jani.nikula at linux.intel.com>
> > Cc: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
> > Acked-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
> > Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>
> > Link: http://patchwork.freedesktop.org/patch/msgid/1449564561-3896-1-git-send-email-daniel.vetter@ffwll.ch
> > ---
> >  Documentation/DocBook/gpu.tmpl | 37 +++++++++++++++++++++++++++++++++++++
> >  1 file changed, 37 insertions(+)
> >
> > diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl
> > index 749b8e2f2113..ce4d6f017242 100644
> > --- a/Documentation/DocBook/gpu.tmpl
> > +++ b/Documentation/DocBook/gpu.tmpl
> > @@ -124,6 +124,43 @@
> >      <para>
> >        [Insert diagram of typical DRM stack here]
> >      </para>
> > +  <sect1>
> > +    <title>Style Guidelines</title>
> > +    <para>
> > +      For consistency these documentations use American English. Abbreviations
> > +      are written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and so
> > +      on. To aid in reading documentations make full use of the markup
> > +      characters kerneldoc provides: @parameter for function paramters, @member
> > +      for structure members, &structure to refernce structures and
> > +      function() for functions. These all get automatically hyperlinked if
> > +      kerneldoc for the referencec objects exists When referencing entries in
> > +      function vtables please use -<vfunc(). Note that with kerneldoc does
> > +      not support referncing struct members directly, so please add a reference
> > +      to the vtable struct somewhere in the same paragraph or at least section.
> > +    </para>
> > +    <para>
> > +      Except in special situations (to separate locked from unlocked variants)
> > +      locking requirements for functions aren't documented in the kerneldoc.
> > +      Instead locking should be check at runtime using e.g.
> > +      <code>WARN_ON(!mutex_is_locked(...));</code>. Since it's much easier to
> > +      ignore documentation than runtime noise this provides more value. And on
> > +      top of that runtime checks do need to be updated when the locking rules
> > +      change, increasing the changes that they're correct. Within the
> > +      documentation the locking rules should be explained in the relevant
> > +      structures: Either in the comment for the lock explaining what it
> > +      protects, or data fields need a note about which lock protects them, or
> > +      both.
> > +    </para>
> > +    <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.
> > +    </para>
> > +  </sect1>
> >    </chapter>
> >  
> >    <!-- Internals -->
> 
> -- 
> Jani Nikula, Intel Open Source Technology Center

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch