From: Jonathan Corbet <corbet@lwn.net>
To: Peter Lister <peter@bikeshed.quignogs.org.uk>
Cc: Jani Nikula <jani.nikula@linux.intel.com>,
Matthew Wilcox <willy@infradead.org>,
linux-kernel@vger.kernel.org,
Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
"Rafael J. Wysocki" <rafael@kernel.org>,
linux-doc@vger.kernel.org
Subject: Re: [PATCH v3 0/1] Compactly make code examples into literal blocks
Date: Mon, 30 Mar 2020 16:32:55 -0600 [thread overview]
Message-ID: <20200330163255.4322e763@lwn.net> (raw)
In-Reply-To: <7d7f4cbb-e8e8-411d-62f4-7a32a2ac8d8a@bikeshed.quignogs.org.uk>
On Mon, 30 Mar 2020 23:29:24 +0100
Peter Lister <peter@bikeshed.quignogs.org.uk> wrote:
One quick thing caught my eye...
> One head-on approachis to literalise *all* kerneldoc comments for
> functions and structures. The kerneldoc keywords then serve only to
> generate links; the ReST output is minimal but guaranteed validand
> warning free. Would any readers of API docs be inconvenienced? The
> target readership are presumably programmers, and the searchability of
> the sphinx RTD is more useful to me than the formatting.
The ability to put formatting directive into kerneldoc comments was one of
the driving forces that pushed the RST switch in the first place. There
are subsystems that make use of this capability and would not be pleased
to see it go away.
jon
next prev parent reply other threads:[~2020-03-30 22:32 UTC|newest]
Thread overview: 21+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-03-11 19:22 [PATCH 0/1] Format kerneldoc code snippets as literal block peter
2020-03-11 19:22 ` [PATCH 1/1] Added double colons and blank lines within kerneldoc to format code snippets as ReST literal blocks peter
2020-03-11 19:30 ` Jonathan Corbet
2020-03-26 19:16 ` [PATCH v2 0/1] Compactly make code examples into " peter
2020-03-26 19:16 ` [PATCH v2 1/1] A compact idiom to add code examples in kerneldoc comments peter
2020-03-26 19:29 ` Matthew Wilcox
2020-03-26 19:36 ` Peter Lister
2020-03-26 19:51 ` [PATCH v3 0/1] Compactly make code examples into literal blocks peter
2020-03-26 19:51 ` [PATCH v3 1/1] A compact idiom to add code examples in kerneldoc comments peter
2020-03-26 19:54 ` Matthew Wilcox
2020-03-27 6:32 ` Greg Kroah-Hartman
2020-03-27 11:28 ` [PATCH v3 0/1] Compactly make code examples into literal blocks Jani Nikula
2020-03-27 16:41 ` Jonathan Corbet
2020-03-27 16:50 ` Matthew Wilcox
2020-03-27 17:11 ` Jonathan Corbet
2020-03-27 17:35 ` Matthew Wilcox
2020-03-31 11:22 ` Jani Nikula
2020-03-31 10:50 ` Jani Nikula
2020-03-30 22:29 ` Peter Lister
2020-03-30 22:32 ` Jonathan Corbet [this message]
2020-03-31 11:54 ` Jani Nikula
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=20200330163255.4322e763@lwn.net \
--to=corbet@lwn.net \
--cc=gregkh@linuxfoundation.org \
--cc=jani.nikula@linux.intel.com \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=peter@bikeshed.quignogs.org.uk \
--cc=rafael@kernel.org \
--cc=willy@infradead.org \
/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;
as well as URLs for NNTP newsgroup(s).