From mboxrd@z Thu Jan 1 00:00:00 1970 From: Thierry Reding Subject: Re: [PATCH] drm: Documentation style guide Date: Mon, 14 Dec 2015 16:39:06 +0100 Message-ID: <20151214153906.GB1998@ulmo> References: <20151209151942.GA29631@wunner.de> <1449677282-30832-1-git-send-email-daniel.vetter@ffwll.ch> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="===============0686432401==" Return-path: In-Reply-To: <1449677282-30832-1-git-send-email-daniel.vetter@ffwll.ch> List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: intel-gfx-bounces@lists.freedesktop.org Sender: "Intel-gfx" To: Daniel Vetter Cc: Daniel Vetter , Intel Graphics Development , Laurent Pinchart , DRI Development List-Id: dri-devel@lists.freedesktop.org --===============0686432401== Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="GRPZ8SYKNexpdSJ7" Content-Disposition: inline --GRPZ8SYKNexpdSJ7 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable 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. >=20 > v2: Spelling fixes from Pierre, Laurent and Jani. >=20 > v3: More spelling fixes from Lukas. >=20 > Cc: Pierre Moreau > Cc: Jani Nikula > Cc: Laurent Pinchart > Cc: Lukas Wunner > Acked-by: Laurent Pinchart > Signed-off-by: Daniel Vetter > 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(+) >=20 > diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.t= mpl > index 749b8e2f2113..c66d6412f573 100644 > --- a/Documentation/DocBook/gpu.tmpl > +++ b/Documentation/DocBook/gpu.tmpl > @@ -124,6 +124,43 @@ > > [Insert diagram of typical DRM stack here] > > + > + Style Guidelines > + > + For consistency this documentation uses American English. Abbrevia= tions > + 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 "..., 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,= @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 entr= ies in > + function vtables please use ->vfunc(). Note that kerneldoc does > + not support referencing struct members directly, so please add a r= eference > + to the vtable struct somewhere in the same paragraph or at least s= ection. > + > + > + Except in special situations (to separate locked from unlocked var= iants) > + locking requirements for functions aren't documented in the kernel= doc. > + Instead locking should be check at runtime using e.g. "should be checked" > + WARN_ON(!mutex_is_locked(...));. Since it's much easi= er 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 the= m, or > + both. I think you're supposed to have the "or" only in the final subsentence: "either ... protects, data fields need ..., or both." > + > + > + Functions which have a non-void return value should h= ave 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 I 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 --GRPZ8SYKNexpdSJ7 Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v2 iQIcBAABCAAGBQJWbuKYAAoJEN0jrNd/PrOhbpwP/3udf0Yb96S77u7j1c91upv0 OyuJqDqY+QZ8LILYnxWXaeaVM2iMVvkr1n80Nc7UkNWxKtEIWyIxPj6uXoonws9V ozlD23pcvAlSO6O4j98iaZ+CtqP8m3WUzOgDgTbbRTAxLxGD1DsafFvmc3pdBVEk bOkKbnbk1FuAlToJZ4miVsUSSNYKwEQD8cRnMgCYXpS7J1TIM53o8E3i9aBqiyRs ClBJvAUT30wz546IWwjTLRBgAiwwSarQG5AQraGGoInsoy4SgJ+32AOxs5C6qxy9 zOR55Hv7nfnIoXuIP6pGmekR989UX2Djykg/TC26PiBrSZBOIwfrvRQOHmnm0TJF mY0lOmTlpuUh6fmUh0KJIHawW/zS4iAiaf3X6GdQ8Wv5yhY51GctZylGtuznMAFq o16HUlTnqd4hdaydk2r7+nnifelcRZn9Dymrzj8l5/NBXQn740liliYFLs/UpqCt 88d2PCI89n9YP7QH3a0SQjcNrS/JSVyAq/gih/bzeGd5tDbadeoBK2dUGaXP2MOe fShx52CIQ2kcuoHhjzKn3pOFk23B57betMmKZ6OTq3/KDbx3nFgtBYzFL7JtRAPz gDInE3IQURGFqvruMJ+38/9y1NZMwc5h1RglZxr256TJ4fWnW2eQVJM7aMVTwn6G H6RFO6FMew7ThO8W5gtg =fws7 -----END PGP SIGNATURE----- --GRPZ8SYKNexpdSJ7-- --===============0686432401== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: base64 Content-Disposition: inline X19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX18KSW50ZWwtZ2Z4 IG1haWxpbmcgbGlzdApJbnRlbC1nZnhAbGlzdHMuZnJlZWRlc2t0b3Aub3JnCmh0dHA6Ly9saXN0 cy5mcmVlZGVza3RvcC5vcmcvbWFpbG1hbi9saXN0aW5mby9pbnRlbC1nZngK --===============0686432401==--