From: Jani Nikula <jani.nikula@linux.intel.com>
To: Jonathan Corbet <corbet@lwn.net>, Sam Ravnborg <sam@ravnborg.org>
Cc: "Maxime Ripard" <maxime.ripard@bootlin.com>,
"Jonathan Neuschäfer" <j.neuschaefer@gmx.net>,
dri-devel@lists.freedesktop.org, linux-kernel@vger.kernel.org,
"David Airlie" <airlied@linux.ie>,
"Mauro Carvalho Chehab" <mchehab+samsung@kernel.org>,
"Sean Paul" <sean@poorly.run>
Subject: Re: Best practice for embedded code samles? [Was: drm/drv: Use // for comments in example code]
Date: Wed, 14 Aug 2019 10:37:59 +0300 [thread overview]
Message-ID: <8736i4gpt4.fsf@intel.com> (raw)
In-Reply-To: <20190813160726.3f9eb8c8@lwn.net>
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
next prev parent reply other threads:[~2019-08-14 7:38 UTC|newest]
Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top
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 [this message]
2019-08-19 17:06 ` [PATCH] drm/drv: Use // for comments in example code Sam Ravnborg
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=8736i4gpt4.fsf@intel.com \
--to=jani.nikula@linux.intel.com \
--cc=airlied@linux.ie \
--cc=corbet@lwn.net \
--cc=dri-devel@lists.freedesktop.org \
--cc=j.neuschaefer@gmx.net \
--cc=linux-kernel@vger.kernel.org \
--cc=maxime.ripard@bootlin.com \
--cc=mchehab+samsung@kernel.org \
--cc=sam@ravnborg.org \
--cc=sean@poorly.run \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox