Re: [PATCH] drm: Documentation style guide

On Wed, Dec 09, 2015 at 11:41:31AM +0100, Daniel Vetter 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.

Cc: Pierre Moreau pierre.morrow@free.fr Cc: Jani Nikula jani.nikula@linux.intel.com Cc: Laurent Pinchart laurent.pinchart@ideasonboard.com Acked-by: Laurent Pinchart laurent.pinchart@ideasonboard.com Signed-off-by: Daniel Vetter daniel.vetter@intel.com Link: http://patchwork.freedesktop.org/patch/msgid/1449564561-3896-1-git-send-emai...

Ok I pulled that one in, thanks for all the comments. Like I said in this thread, this is just a start. So if anyone has an OCD doc style thing, please just add it here. -Daniel

---

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 -->

-- 2.5.1