On 14/12/15 15:39, Thierry Reding wrote:
On Wed, Dec 09, 2015 at 05:08:02PM +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.
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-emai...
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. Abbreviationsare written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and soon. To aid in reading, documentations make full use of the markup"..., the documentation makes full use of..." and perhaps "makes use of the full set of markup characters that kerneldoc provides".
characters kerneldoc provides: @parameter for function parameters, @memberfor structure members, &structure to reference structures andfunction() for functions. These all get automatically hyperlinked ifkerneldoc for the referenced objects exists. When referencing entries infunction vtables please use ->vfunc(). Note that kerneldoc doesnot support referencing struct members directly, so please add a referenceto 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."should be checked"
<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 chances that they're correct. Within the
A few commas to delimit subclauses would make this more readable:
Since it's much easier to ignore documentation than runtime noise, this provides more value. And on top of that, runtime checks have to be updated when the locking rules change, thus increasing the chances that they're correct.
documentation 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.I think you're supposed to have the "or" only in the final subsentence:
"either ... protects, data fields need ..., or both."
Within the documentation, the locking rules should be explained in comments on the relevant structures; these comments may be with the lock, explaining what it protects, or with the data, noting which lock protects it, or both -- in which case they should agree!
</para>
<para>
Functions which have a non-<code>void</code> return value should have asection called "Returns" explaining the expected return values indifferent cases and 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 sectionI thought the colon was necessary for kerneldoc to turn it into a section?
Overall, long overdue, so thanks for writing it up:
Acked-by: Thierry Reding treding@nvidia.com
Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx