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@xxxxxxxxx> > > --- > > > > 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, &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 -<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@xxxxxxxxxxxxxxxx> > > 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 --> -- Regards, Laurent Pinchart _______________________________________________ Intel-gfx mailing list Intel-gfx@xxxxxxxxxxxxxxxxxxxxx http://lists.freedesktop.org/mailman/listinfo/intel-gfx
