From mboxrd@z Thu Jan 1 00:00:00 1970 From: Thierry Reding Subject: Re: [PATCH 3/7] drm/doc: Add GEM/CMA helpers to kerneldoc Date: Wed, 5 Nov 2014 16:16:24 +0100 Message-ID: <20141105151623.GD24353@ulmo> References: <1415193919-1687-1-git-send-email-thierry.reding@gmail.com> <1415193919-1687-4-git-send-email-thierry.reding@gmail.com> <20141105143440.GO26941@phenom.ffwll.local> <20141105150124.GC24353@ulmo> <20141105150455.GU26941@phenom.ffwll.local> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="===============1155285016==" Return-path: Received: from mail-wi0-f178.google.com (mail-wi0-f178.google.com [209.85.212.178]) by gabe.freedesktop.org (Postfix) with ESMTP id E37EA6E961 for ; Wed, 5 Nov 2014 07:16:30 -0800 (PST) Received: by mail-wi0-f178.google.com with SMTP id bs8so324993wib.11 for ; Wed, 05 Nov 2014 07:16:26 -0800 (PST) In-Reply-To: <20141105150455.GU26941@phenom.ffwll.local> List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" To: Daniel Vetter Cc: Benjamin Gaignard , Daniel Vetter , dri-devel@lists.freedesktop.org, Tomi Valkeinen , Archit Taneja , Laurent Pinchart , Russell King , Dave Airlie List-Id: dri-devel@lists.freedesktop.org --===============1155285016== Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="UoPmpPX/dBe4BELn" Content-Disposition: inline --UoPmpPX/dBe4BELn Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Wed, Nov 05, 2014 at 04:04:55PM +0100, Daniel Vetter wrote: > On Wed, Nov 05, 2014 at 04:01:26PM +0100, Thierry Reding wrote: > > On Wed, Nov 05, 2014 at 03:34:40PM +0100, Daniel Vetter wrote: > > > On Wed, Nov 05, 2014 at 02:25:15PM +0100, Thierry Reding wrote: > > > > + * Return: A struct drm_gem_cma_object * on success or an ERR_PTR(= )-encoded > > >=20 > > > Same bikeshed about "Returns:\n" as with the panel kerneldoc patch. > >=20 > > I've been following the style described in the kernel-doc nano-HOWTO, > > which says that: > >=20 > > The return value, if any, should be described in a dedicated > > section named "Return". > >=20 > > There are other things in that document that we don't follow in DRM, so > > I wonder if we should just consider it as guidelines rather than actual > > rules (they aren't enforced anyway) or perhaps make a pass over existing > > kerneldoc and convert it to the rules described in that document. > >=20 > > That document is the only reference for the kerneldoc syntax (that I > > know of), so I had always thought that we should be following it. >=20 > We've started out with all-uppercase RETURNS from userspace libdrm iirc. I > don't care really, but iirc the Returns: is the common one we use. Imo it > also reads better in English, but not native speaker here ;-) Alright, I'll go with the variant that you proposed for the sake of consistency. Thierry --UoPmpPX/dBe4BELn Content-Type: application/pgp-signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v2 iQIcBAEBAgAGBQJUWj9HAAoJEN0jrNd/PrOhIsoP/jcgs1ipJhmvr/ttzsnrYHlx g3j7Qi0Pyja+M5yT847O4oTus9wst3o7DHA/x3l3A5ZT+PSdMSAMz/cF8cHvIJS/ pjwv2ZVr22cklxWhELsNJwZWxvRdBFGhF2A/1tCOiiHXP6cI1+QfAmkkFC96OQoR wT0itTn8bqlarmcNYLKIAZZ/FhwYPVyH+LzcK4muRczztQxSuZW6hdUM6SZOC3LP 2JOTcvLnuo4B1FPSpAgOvq+/dd5cSBvSF3oxubsIRu01K08JJoKRefrg8iGSAHo0 2HqgZ4z5ddPxQqlLgMKEfMWTmLIAPWuJ48Z454Mx3zkr8r3ESbjnDSnGRoqjE/oj 1GUh8x3o+t9TtlB2CwWPGNylaxfzAG6kiHKqVcI5tBrwzTBxGVQ6XyvVLY8xw2NF iGg93FIxXlw6Gzu3wmEUGyjuO37s5y+IruLd1BaspJj/zBPYo0595gKT50B7kY6U PxdqXqekCUrItpuxxx0041IgkHTRhE0I8AZSf6pPua/kas2mfy2C9jnddScMjrE/ bdFWG/7zMDfNCF48QkY8zSa6wOCJFn2zMjmEw5oXbYrvSOxjr3UmI83YT6/Hucxe T6M/brAdgh4KLDyVTvxw9K4tXYKXPzG4HslFLbCVVJuB25j5Br/ejVHQz212jAXg iRMfNGe9ZbzDUOXOrvxe =w9+h -----END PGP SIGNATURE----- --UoPmpPX/dBe4BELn-- --===============1155285016== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: base64 Content-Disposition: inline X19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX18KZHJpLWRldmVs IG1haWxpbmcgbGlzdApkcmktZGV2ZWxAbGlzdHMuZnJlZWRlc2t0b3Aub3JnCmh0dHA6Ly9saXN0 cy5mcmVlZGVza3RvcC5vcmcvbWFpbG1hbi9saXN0aW5mby9kcmktZGV2ZWwK --===============1155285016==--