Re: [PATCH v3 0/1] Compactly make code examples into literal blocks

On Fri, Mar 27, 2020 at 11:11:06AM -0600, Jonathan Corbet wrote:

On Fri, 27 Mar 2020 09:50:22 -0700
Matthew Wilcox [off-list ref] wrote:

quoted

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 :)

Happy to help out!

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.

I certainly see the value in consistency throughout our documentation.
But I don't think it's a given that the documentation of the return
value is necessarily its own section.  I see kernel-doc as being more
about semantic markup and the rst files as being a presentation markup.

So I'm fine with Return:: introducing a list or Example:: introducing
a code section; these are special purpose keywords.  I'm not a fan of
using raw rst in kernel-doc.  Of course if we can make the kernel-doc
and rst languages the same for the same concepts, that's great.