[1/5,RFC] drm: Documentation style guide
diff mbox

Message ID 1449564561-3896-1-git-send-email-daniel.vetter@ffwll.ch
State New
Headers show

Commit Message

Daniel Vetter Dec. 8, 2015, 8:49 a.m. UTC
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(+)

Comments

Pierre Moreau Dec. 8, 2015, 9:59 a.m. UTC | #1
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. 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 paramters, @member

paramters -> parameters

> +      for structure members, &amp;structure to refernce structures and

refernce -> reference

> +      function() for functions. These all get automatically hyperlinked if
> +      kerneldoc for the referencec objects exists When referencing entries in

referencec -> referenced, missing '.' after exists

> +      function vtables please use -&lt;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 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 changes 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 an 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.

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
Daniel Vetter Dec. 8, 2015, 10:14 a.m. UTC | #2
On Tue, Dec 08, 2015 at 10:59:05AM +0100, Pierre Moreau wrote:
> On 09:49 AM - Dec 08 2015, Daniel Vetter wrote:
> > +    <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 an 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.
> 
> 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.

There is a massive pile of these docs, and there is a slight difference in
how vfunc table section headings and function reference section headings
are rendered. Given that I figured I'll start modestly.

But if you feel like making this consistent I'd definitely take a patch to
do so. Same really for any of the other style guideline issues. Well,
after we have some acks on this, and any large-scale style change should
first do the RFC patch for this section for discussion to avoid the risk
of wasting lots of time.
-Daniel
Laurent Pinchart Dec. 8, 2015, 1:49 p.m. UTC | #3
Hello,

On Tuesday 08 December 2015 10:59:05 Pierre Moreau wrote:
> 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.
> > 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 paramters,
> > @member
>
> paramters -> parameters
> 
> > +      for structure members, &amp;structure to refernce structures and
> 
> refernce -> reference
> 
> > +      function() for functions. These all get automatically hyperlinked
> > if
> > +      kerneldoc for the referencec objects exists When referencing
> > entries in
>
> referencec -> referenced, missing '.' after exists
> 
> > +      function vtables please use -&lt;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 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 changes that they're correct. Within the

s/changes/chances/

> > +      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 an their meanings. Currently there's no consensus

s/an/and/

Apart from that,

Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

> > 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.
> 
> 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.
> 
> > +    </para>
> > +  </sect1>
> > 
> >    </chapter>
> >    <!-- Internals -->

Patch
diff mbox

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. 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 paramters, @member
+      for structure members, &amp;structure to refernce structures and
+      function() for functions. These all get automatically hyperlinked if
+      kerneldoc for the referencec objects exists When referencing entries in
+      function vtables please use -&lt;vfunc(). Note that with kerneldoc does
+      not support referncing 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 changes 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 an 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 -->