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@xxxxxxx> Cc: Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> Cc: Laurent Pinchart <laurent.pinchart@xxxxxxxxxxxxxxxx> Cc: Lukas Wunner <lukas@xxxxxxxxx> Acked-by: Laurent Pinchart <laurent.pinchart@xxxxxxxxxxxxxxxx> Signed-off-by: Daniel Vetter <daniel.vetter@xxxxxxxxx> Link: http://patchwork.freedesktop.org/patch/msgid/1449564561-3896-1-git-send-email-daniel.vetter@xxxxxxxx --- Documentation/DocBook/gpu.tmpl | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl index 749b8e2f2113..c66d6412f573 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 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 --> -- 2.5.1 _______________________________________________ Intel-gfx mailing list Intel-gfx@xxxxxxxxxxxxxxxxxxxxx http://lists.freedesktop.org/mailman/listinfo/intel-gfx
