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

[Jani Nikula]

On Fri, 27 Mar 2020, Matthew Wilcox <willy@xxxxxxxxxxxxx> wrote:
> On Fri, Mar 27, 2020 at 11:11:06AM -0600, Jonathan Corbet wrote:
>> On Fri, 27 Mar 2020 09:50:22 -0700
>> Matthew Wilcox <willy@xxxxxxxxxxxxx> 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 :)
>
> 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 don't really think it would need to be a sphinx extension. If I were
to do this from scratch, I'd just leave it be any convention that's
compatible with rst. Perhaps field lists [1], for both parameters and
return values. With that you could do things like:

 * :Returns: 0 on success.
 * :Returns: -ENOCOFFEE when out of coffee.
 * :Returns: Other negative error codes for other errors.

or:

 * :Returns: 0 on success, -ENOCOFFEE when out of coffee, and other negative
 *           error codes for other errors.

according to your tastes, and both render nicely. You could actually
start using those *now* without changes to kernel-doc or anything. Try
it!

(Side note, I think it would be nice to preprocess the current @param:
stuff into field lists instead of the definition lists that we use now.)

> 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.

IMO, if you want to make a list, you use rst lists. If you want to add a
preformatted text block, you use rst preformatted text block. I don't
see any reason why those should be tied to certain headings such as
"return" or "example". Return does not have to be a list, and example
does not have to be a preformatted block.

I am also not a fan of *overusing* rst in kernel-doc. But we have it
there so that you can use it when you need it, and not have to hack at
the godawful kernel-doc the perl script every time. So that you can just
point at the widely available documentation on rst for doing everything,
instead of telling people to go figure it out from the perl source.

BR,
Jani.


[1] https://docutils.sourceforge.io/docs/user/rst/quickref.html#field-lists

-- 
Jani Nikula, Intel Open Source Graphics Center