drm/drv: Use // for comments in example code
Subsystems (2)
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
@@ -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
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 lexliteral_blockas "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.
Signed-off-by Jonathan Neuschäfer <[email protected]>
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@@ -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
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
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
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 lexliteral_blockas "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.
Signed-off-by Jonathan Neuschäfer <[email protected]>
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