Hello Daniel,
Just some typo comments below.
On 09:49 AM - Dec 08 2015, 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.
Signed-off-by: Daniel Vetter daniel.vetter@intel.com
Documentation/DocBook/gpu.tmpl | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+)
diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl index 86e5b12a49ba..5698c93dae8b 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. Abbreviationsare written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and soon. To aid in reading documentations make full use of the markupcharacters kerneldoc provides: @parameter for function paramters, @member
paramters -> parameters
for structure members, &structure to refernce structures and
refernce -> reference
function() for functions. These all get automatically hyperlinked ifkerneldoc for the referencec objects exists When referencing entries in
referencec -> referenced, missing '.' after exists
function vtables please use -<vfunc(). Note that with kerneldoc does
Isn't "with" too much here? "Note that kerneldoc does not […]"?
not support referncing struct members directly, so please add a reference
referncing -> referencing
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 toignore documentation than runtime noise this provides more value. And ontop of that runtime checks do need to be updated when the locking ruleschange, increasing the changes that they're correct. Within thedocumentation the locking rules should be explained in the relevantstructures: Either in the comment for the lock explaining what itprotects, or data fields need a note about which lock protects them, orboth.</para>
<para>
Functions which have a non-<code>void</code> return value should have asection called "Returns" explaining the expected return values indifferent cases an their meanings. Currently there's no consensus whetherthat section name should be all upper-case or not, and whether it shouldend in a colon or not. Go with the file-local style. Other common sectionnames are "Notes" with information for dangerous or tricky corner cases,and "FIXME" where the interface could be cleaned up.
Why not define (and use) a single style for naming all sections? Old documentation might not use it, but it should be doable to upgrade those old documents.
Pierre
</para>
</sect1> </chapter>
<!-- Internals -->
-- 2.5.1
dri-devel mailing list dri-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/dri-devel