Best practice for embedded code samles? [Was: drm/drv: Use // for comments in example code]

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