Message ID | 1449657691-6632-1-git-send-email-daniel.vetter@ffwll.ch (mailing list archive) |
---|---|
State | New, archived |
Headers | show |
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 <pierre.morrow@free.fr> > Cc: Jani Nikula <jani.nikula@linux.intel.com> > Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com> > 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-email-daniel.vetter@ffwll.ch 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, &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 -<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 >
On Wed, 09 Dec 2015, Daniel Vetter <daniel.vetter@ffwll.ch> 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 <pierre.morrow@free.fr> > Cc: Jani Nikula <jani.nikula@linux.intel.com> > Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com> > 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-email-daniel.vetter@ffwll.ch > --- > 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, &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 -<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 -->
On Wednesday 09 December 2015 13:21:09 Jani Nikula wrote: > On Wed, 09 Dec 2015, Daniel Vetter <daniel.vetter@ffwll.ch> 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 ?
On Wed, Dec 09, 2015 at 01:21:09PM +0200, Jani Nikula wrote: > On Wed, 09 Dec 2015, Daniel Vetter <daniel.vetter@ffwll.ch> 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 <pierre.morrow@free.fr> > > Cc: Jani Nikula <jani.nikula@linux.intel.com> > > Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com> > > 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-email-daniel.vetter@ffwll.ch > > --- > > 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, &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 -<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
On Wed, 09 Dec 2015, Laurent Pinchart <laurent.pinchart@ideasonboard.com> wrote: > On Wednesday 09 December 2015 13:21:09 Jani Nikula wrote: >> On Wed, 09 Dec 2015, Daniel Vetter <daniel.vetter@ffwll.ch> 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.
On Wednesday 09 December 2015 16:17:47 Jani Nikula wrote: > On Wed, 09 Dec 2015, Laurent Pinchart <laurent.pinchart@ideasonboard.com> wrote: > > On Wednesday 09 December 2015 13:21:09 Jani Nikula wrote: > >> On Wed, 09 Dec 2015, Daniel Vetter <daniel.vetter@ffwll.ch> 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/
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, &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> Otherwise looks nice, thank you! Best regards, Lukas
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, &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 -<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 -->