* [PATCH] drm/drv: Use // for comments in example code
@ 2019-08-08 16:36 Jonathan Neuschäfer
2019-08-11 21:32 ` Best practice for embedded code samles? [Was: drm/drv: Use // for comments in example code] Sam Ravnborg
2019-08-19 17:06 ` [PATCH] drm/drv: Use // for comments in example code Sam Ravnborg
0 siblings, 2 replies; 5+ messages in thread
From: Jonathan Neuschäfer @ 2019-08-08 16:36 UTC (permalink / raw)
To: dri-devel
Cc: Jonathan Neuschäfer, Maarten Lankhorst, Maxime Ripard,
Sean Paul, David Airlie, Daniel Vetter, linux-kernel
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>
---
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
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Best practice for embedded code samles? [Was: drm/drv: Use // for comments in example code]
2019-08-08 16:36 [PATCH] drm/drv: Use // for comments in example code Jonathan Neuschäfer
@ 2019-08-11 21:32 ` Sam Ravnborg
2019-08-13 22:07 ` Jonathan Corbet
2019-08-19 17:06 ` [PATCH] drm/drv: Use // for comments in example code Sam Ravnborg
1 sibling, 1 reply; 5+ messages in thread
From: Sam Ravnborg @ 2019-08-11 21:32 UTC (permalink / raw)
To: Jonathan Neuschäfer, Mauro Carvalho Chehab, Jonathan Corbet
Cc: dri-devel, Maxime Ripard, linux-kernel, David Airlie, Sean Paul
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
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Best practice for embedded code samles? [Was: drm/drv: Use // for comments in example code]
2019-08-11 21:32 ` Best practice for embedded code samles? [Was: drm/drv: Use // for comments in example code] Sam Ravnborg
@ 2019-08-13 22:07 ` Jonathan Corbet
2019-08-14 7:37 ` Jani Nikula
0 siblings, 1 reply; 5+ messages in thread
From: Jonathan Corbet @ 2019-08-13 22:07 UTC (permalink / raw)
To: Sam Ravnborg
Cc: Jonathan Neuschäfer, Mauro Carvalho Chehab, dri-devel,
Maxime Ripard, linux-kernel, David Airlie, Sean Paul
On Sun, 11 Aug 2019 23:32:15 +0200
Sam Ravnborg <sam@ravnborg.org> 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
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Best practice for embedded code samles? [Was: drm/drv: Use // for comments in example code]
2019-08-13 22:07 ` Jonathan Corbet
@ 2019-08-14 7:37 ` Jani Nikula
0 siblings, 0 replies; 5+ messages in thread
From: Jani Nikula @ 2019-08-14 7:37 UTC (permalink / raw)
To: Jonathan Corbet, Sam Ravnborg
Cc: Maxime Ripard, Jonathan Neuschäfer, dri-devel, linux-kernel,
David Airlie, Mauro Carvalho Chehab, Sean Paul
On Tue, 13 Aug 2019, Jonathan Corbet <corbet@lwn.net> wrote:
> On Sun, 11 Aug 2019 23:32:15 +0200
> Sam Ravnborg <sam@ravnborg.org> 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.
Not really a Sphinx limitation, is it? You can't embed a /* */ block
comment within a /* */ block comment anyway, Sphinx or not.
BR,
Jani.
--
Jani Nikula, Intel Open Source Graphics Center
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] drm/drv: Use // for comments in example code
2019-08-08 16:36 [PATCH] drm/drv: Use // for comments in example code Jonathan Neuschäfer
2019-08-11 21:32 ` Best practice for embedded code samles? [Was: drm/drv: Use // for comments in example code] Sam Ravnborg
@ 2019-08-19 17:06 ` Sam Ravnborg
1 sibling, 0 replies; 5+ messages in thread
From: Sam Ravnborg @ 2019-08-19 17:06 UTC (permalink / raw)
To: Jonathan Neuschäfer
Cc: dri-devel, Maxime Ripard, linux-kernel, David Airlie, Sean Paul
Hi Jonathan.
Thanks for making this more readable in the html output.
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>
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
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2019-08-19 17:07 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-08-08 16:36 [PATCH] drm/drv: Use // for comments in example code Jonathan Neuschäfer
2019-08-11 21:32 ` Best practice for embedded code samles? [Was: drm/drv: Use // for comments in example code] Sam Ravnborg
2019-08-13 22:07 ` Jonathan Corbet
2019-08-14 7:37 ` Jani Nikula
2019-08-19 17:06 ` [PATCH] drm/drv: Use // for comments in example code Sam Ravnborg
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).