Skip to contentSkip to conversation

drm/drv: Use // for comments in example code

PATCH In review Jonathan Neuschäfer 4 participants 5 messages Aug 8, 2019 – Aug 19, 2019

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 drm/drv: Use // for comments in example code

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.

---
 drivers/gpu/drm/drm_drv.c | 14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)
drivers/gpu/drm/drm_drv.c +6 -8
index 9d00947ca447..769feefeeeef 100644
@@ -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

#1 lore raw

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

Quoted 7 lines · Jonathan Neuschäfer

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.

Quoted 7 lines

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.

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

Quoted 57 lines
---
 drivers/gpu/drm/drm_drv.c | 14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)
drivers/gpu/drm/drm_drv.c +6 -9
index 9d00947ca447..769feefeeeef 100644
@@ -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
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel

#2 lore raw

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

Quoted 5 lines · On Sun, 11 Aug 2019 23:32:15 +0200 Sam Ravnborg <[email protected]> wrote:

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.

If you're embedding a code sample *into a code comment* then I suspect this is about as good as it gets. The alternative is to put it in as a plain literal text block. That would lose the syntax highlighting; I think that's an entirely bearable cost, but others seem to feel differently about it.

Thanks,

jon
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel

#3 lore raw

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

Quoted 6 lines · Jonathan Corbet
Quoted 3 lines · On Sun, 11 Aug 2019 23:32:15 +0200 Sam Ravnborg <[email protected]> wrote:

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

Quoted 8 lines
Quoted 2 lines

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

If you're embedding a code sample *into a code comment* then I suspect this is about as good as it gets. The alternative is to put it in as a plain literal text block. That would lose the syntax highlighting; I think that's an entirely bearable cost, but others seem to feel differently about it.

Not really a Sphinx limitation, is it? You can't embed a /* */ block comment within a /* */ block comment anyway, Sphinx or not.

BR,
Jani.

Signature · 1 line
Jani Nikula, Intel Open Source Graphics Center
#4 lore raw
In reply to Jonathan Neuschäfer

Hi Jonathan.

Thanks for making this more readable in the html output.

Quoted 7 lines · Jonathan Neuschäfer

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.

Quoted 7 lines

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.

I got Acked-by from Daniel Vetter and has now applied this patch to drm-misc-next.
It will show up in linux-next after the merge window.

Sam