From: Jonathan Corbet <corbet@lwn.net>
To: Matthew Wilcox <willy@infradead.org>
Cc: Jani Nikula <jani.nikula@linux.intel.com>,
peter@bikeshed.quignogs.org.uk, 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: Fri, 27 Mar 2020 11:11:06 -0600 [thread overview]
Message-ID: <20200327111106.57982763@lwn.net> (raw)
In-Reply-To: <20200327165022.GP22483@bombadil.infradead.org>
On Fri, 27 Mar 2020 09:50:22 -0700
Matthew Wilcox <willy@infradead.org> wrote:
> Let me just check I understand Jani's proposal here. You want to change
>
> * Return: Number of pages, or negative errno on failure
>
> to
>
> * Return
> * ~~~~~~
> * Number of pages, or negative errno on failure
>
> If so, I oppose such an increase in verbosity and I think most others
> would too. If not, please let me know what you're actually proposing ;-)
I told you there would be resistance :)
I think a reasonable case can be made for using the same documentation
format throughout our docs, rather than inventing something special for
kerneldoc comments. So I personally don't think the above is terrible,
but as I already noted, I anticipate resistance.
An alternative would be to make a little sphinx extension; then it would
read more like:
.. returns:: Number of pages, except when the moon is full
...which would still probably not be entirely popular.
jon
next prev parent reply other threads:[~2020-03-27 17:11 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 [this message]
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
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=20200327111106.57982763@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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.