drm: Documentation style guide

    <para>

      [Insert diagram of typical DRM stack here]

    </para>

  <sect1>

    <title>Style Guidelines</title>

    <para>

      For consistency this documentation uses 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 parameters, @member

      for structure members, &structure to reference structures and

      function() for functions. These all get automatically hyperlinked if

      kerneldoc for the referenced objects exists. When referencing entries in

      function vtables please use ->vfunc(). Note that kerneldoc does

      not support referencing 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 chances 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 and 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 -->