Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Date:   Sun, 11 Aug 2019 23:32:15 +0200
From:   Sam Ravnborg <sam@ravnborg.org>
To:     Jonathan =?iso-8859-1?Q?Neusch=E4fer?= <j.neuschaefer@gmx.net>,
        Mauro Carvalho Chehab <mchehab+samsung@kernel.org>,
        Jonathan Corbet <corbet@lwn.net>
Cc:     dri-devel@lists.freedesktop.org,
        Maxime Ripard <maxime.ripard@bootlin.com>,
        linux-kernel@vger.kernel.org, David Airlie <airlied@linux.ie>,
        Sean Paul <sean@poorly.run>
Subject: Best practice for embedded code samles? [Was: drm/drv: Use // for
 comments in example code]
Message-ID: <20190811213215.GA26468@ravnborg.org>
References: <20190808163629.14280-1-j.neuschaefer@gmx.net>
MIME-Version: 1.0
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <20190808163629.14280-1-j.neuschaefer@gmx.net>
User-Agent: Mutt/1.10.1 (2018-07-13)
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

On Thu, Aug 08, 2019 at 06:36:28PM +0200, Jonathan Neusch?fer wrote:
> This improves Sphinx output in two ways:
> 
> - It avoids an unmatched single-quote ('), about which Sphinx complained:
> 
>   /.../Documentation/gpu/drm-internals.rst:298:
>     WARNING: Could not lex literal_block as "c". Highlighting skipped.
> 
>   An alternative approach would be to replace "can't" with a word that
>   doesn't have a single-quote.
> 
> - It lets Sphinx format the comments in italics and grey, making the
>   code slightly easier to read.
> 
> Signed-off-by: Jonathan Neusch?fer <j.neuschaefer@gmx.net>

The result looks much better now - thanks.

I wonder if there is a better way to embed a code sample
than reverting to // style comments.

As the kernel do not like // comments we should try to avoid them in
examples.

Mauro/Jon?

	Sam

> ---
>  drivers/gpu/drm/drm_drv.c | 14 ++++++--------
>  1 file changed, 6 insertions(+), 8 deletions(-)
> 
> diff --git a/drivers/gpu/drm/drm_drv.c b/drivers/gpu/drm/drm_drv.c
> index 9d00947ca447..769feefeeeef 100644
> --- a/drivers/gpu/drm/drm_drv.c
> +++ b/drivers/gpu/drm/drm_drv.c
> @@ -328,11 +328,9 @@ void drm_minor_release(struct drm_minor *minor)
>   *		struct drm_device *drm;
>   *		int ret;
>   *
> - *		[
> - *		  devm_kzalloc() can't be used here because the drm_device
> - *		  lifetime can exceed the device lifetime if driver unbind
> - *		  happens when userspace still has open file descriptors.
> - *		]
> + *		// devm_kzalloc() can't be used here because the drm_device '
> + *		// lifetime can exceed the device lifetime if driver unbind
> + *		// happens when userspace still has open file descriptors.
>   *		priv = kzalloc(sizeof(*priv), GFP_KERNEL);
>   *		if (!priv)
>   *			return -ENOMEM;
> @@ -355,7 +353,7 @@ void drm_minor_release(struct drm_minor *minor)
>   *		if (IS_ERR(priv->pclk))
>   *			return PTR_ERR(priv->pclk);
>   *
> - *		[ Further setup, display pipeline etc ]
> + *		// Further setup, display pipeline etc
>   *
>   *		platform_set_drvdata(pdev, drm);
>   *
> @@ -370,7 +368,7 @@ void drm_minor_release(struct drm_minor *minor)
>   *		return 0;
>   *	}
>   *
> - *	[ This function is called before the devm_ resources are released ]
> + *	// This function is called before the devm_ resources are released
>   *	static int driver_remove(struct platform_device *pdev)
>   *	{
>   *		struct drm_device *drm = platform_get_drvdata(pdev);
> @@ -381,7 +379,7 @@ void drm_minor_release(struct drm_minor *minor)
>   *		return 0;
>   *	}
>   *
> - *	[ This function is called on kernel restart and shutdown ]
> + *	// This function is called on kernel restart and shutdown
>   *	static void driver_shutdown(struct platform_device *pdev)
>   *	{
>   *		drm_atomic_helper_shutdown(platform_get_drvdata(pdev));
> --
> 2.20.1
> 
> _______________________________________________
> dri-devel mailing list
> dri-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel