drm: Documentation style guide

Commit Message

Daniel Vetter Dec. 9, 2015, 10:41 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.

v2: Spelling fixes from Pierre, Laurent and Jani.

Cc: Pierre Moreau <[e-mail]>
Cc: Jani Nikula <[e-mail]>
Cc: Laurent Pinchart <[e-mail]>
Acked-by: Laurent Pinchart <[e-mail]>
Signed-off-by: Daniel Vetter <[e-mail]>
Link: http://patchwork.freedesktop.org/patch/msgid/[e-mail]
---
 Documentation/DocBook/gpu.tmpl | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

Comments

Daniel Vetter Dec. 9, 2015, 10:44 a.m. UTC | #1

On Wed, Dec 09, 2015 at 11:41:31AM +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.
> 
> Cc: Pierre Moreau <[e-mail]>
> Cc: Jani Nikula <[e-mail]>
> Cc: Laurent Pinchart <[e-mail]>
> Acked-by: Laurent Pinchart <[e-mail]>
> Signed-off-by: Daniel Vetter <[e-mail]>
> Link: http://patchwork.freedesktop.org/patch/msgid/[e-mail]

Ok I pulled that one in, thanks for all the comments. Like I said in this
thread, this is just a start. So if anyone has an OCD doc style thing,
please just add it here.
-Daniel
> ---
>  Documentation/DocBook/gpu.tmpl | 37 +++++++++++++++++++++++++++++++++++++
>  1 file changed, 37 insertions(+)
> 
> diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl
> index 749b8e2f2113..ce4d6f017242 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 -->
> -- 
> 2.5.1
>

Jani Nikula Dec. 9, 2015, 11:21 a.m. UTC | #2

On Wed, 09 Dec 2015, Daniel Vetter <[e-mail]> 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.

Nah, you ignored my comment about "these documentations use American
English". :/

BR,
Jani.

>
> Cc: Pierre Moreau <[e-mail]>
> Cc: Jani Nikula <[e-mail]>
> Cc: Laurent Pinchart <[e-mail]>
> Acked-by: Laurent Pinchart <[e-mail]>
> Signed-off-by: Daniel Vetter <[e-mail]>
> Link: http://patchwork.freedesktop.org/patch/msgid/[e-mail]
> ---
>  Documentation/DocBook/gpu.tmpl | 37 +++++++++++++++++++++++++++++++++++++
>  1 file changed, 37 insertions(+)
>
> diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl
> index 749b8e2f2113..ce4d6f017242 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 -->

Laurent Pinchart Dec. 9, 2015, 12:35 p.m. UTC | #3

On Wednesday 09 December 2015 13:21:09 Jani Nikula wrote:
> On Wed, 09 Dec 2015, Daniel Vetter <[e-mail]> 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.
> 
> Nah, you ignored my comment about "these documentations use American
> English". :/

Isn't documentation uncountable when meaning information recorded in a 
document ?

Daniel Vetter Dec. 9, 2015, 1:35 p.m. UTC | #4

On Wed, Dec 09, 2015 at 01:21:09PM +0200, Jani Nikula wrote:
> On Wed, 09 Dec 2015, Daniel Vetter <[e-mail]> 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.
> 
> Nah, you ignored my comment about "these documentations use American
> English". :/

Well I did type them all in, but totally failed to run git add before
hitting send. Fixed now.
-Daniel

> 
> BR,
> Jani.
> 
> >
> > Cc: Pierre Moreau <[e-mail]>
> > Cc: Jani Nikula <[e-mail]>
> > Cc: Laurent Pinchart <[e-mail]>
> > Acked-by: Laurent Pinchart <[e-mail]>
> > Signed-off-by: Daniel Vetter <[e-mail]>
> > Link: http://patchwork.freedesktop.org/patch/msgid/[e-mail]
> > ---
> >  Documentation/DocBook/gpu.tmpl | 37 +++++++++++++++++++++++++++++++++++++
> >  1 file changed, 37 insertions(+)
> >
> > diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl
> > index 749b8e2f2113..ce4d6f017242 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 -->
> 
> -- 
> Jani Nikula, Intel Open Source Technology Center

Jani Nikula Dec. 9, 2015, 2:17 p.m. UTC | #5

On Wed, 09 Dec 2015, Laurent Pinchart <[e-mail]> wrote:
> On Wednesday 09 December 2015 13:21:09 Jani Nikula wrote:
>> On Wed, 09 Dec 2015, Daniel Vetter <[e-mail]> 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.
>> 
>> Nah, you ignored my comment about "these documentations use American
>> English". :/
>
> Isn't documentation uncountable when meaning information recorded in a 
> document ?

That was my comment, though not on the list. I also thought it was not
necessary to recommend the use of American English.

It did occur to me perhaps documentations are countable in American
English. ;)


BR,
Jani.

Laurent Pinchart Dec. 9, 2015, 2:32 p.m. UTC | #6

On Wednesday 09 December 2015 16:17:47 Jani Nikula wrote:
> On Wed, 09 Dec 2015, Laurent Pinchart <[e-mail]> 
wrote:
> > On Wednesday 09 December 2015 13:21:09 Jani Nikula wrote:
> >> On Wed, 09 Dec 2015, Daniel Vetter <[e-mail]> 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.
> >> 
> >> Nah, you ignored my comment about "these documentations use American
> >> English". :/
> > 
> > Isn't documentation uncountable when meaning information recorded in a
> > document ?
> 
> That was my comment, though not on the list. I also thought it was not
> necessary to recommend the use of American English.
> 
> It did occur to me perhaps documentations are countable in American
> English. ;)

https://lwn.net/Articles/636286/

Lukas Wunner Dec. 9, 2015, 3:19 p.m. UTC | #7

Hi,

I wouldn't normally nitpick like this but since I was reading it anyway
and you were asking for "OCD doc style thing". :-)

This is a proofread of the force-pushed v2 in drm-intel-nightly
(9a8730ddfe1d).


> +  <sect1>
> +    <title>Style Guidelines</title>
> +    <para>
> +      For consistency this documentation use American English. Abbreviations
                                               ^
                                               s/use/uses/

> +      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
                              ^
                              insert comma

> +      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 -&lt;vfunc(). Note that kerneldoc does
                                      ^
                                      &gt;

> +      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>

Otherwise looks nice, thank you!

Best regards,

Lukas

Patch

diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl
index 749b8e2f2113..ce4d6f017242 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 -->