redonkable
/
alistair23-linux
1
0
Fork 0
Code Releases Activity

drm: Documentation style guide 

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.

v3: More spelling fixes from Lukas.

Cc: Pierre Moreau <pierre.morrow@free.fr>
Cc: Jani Nikula <jani.nikula@linux.intel.com>
Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Cc: Lukas Wunner <lukas@wunner.de>
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-email-daniel.vetter@ffwll.ch
hifive-unleashed-5.1
Daniel Vetter 2015-12-08 09:49:17 +01:00
parent 36b66080dc
commit fb9f7a6b06
1 changed files with 37 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
Documentation/DocBook/gpu.tmpl
View File

@ -124,6 +124,43 @@
<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, &amp;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 -&gt;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 -->