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 10:41:26AM -0600, Jonathan Corbet wrote:
>> On Fri, 27 Mar 2020 13:28:54 +0200
>> Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> wrote:
>> 
>> > IMHO the real problem is kernel-doc doing too much preprocessing on the
>> > input, preventing us from doing what would be the sensible thing in
>> > rst. The more we try to fix the problem by adding more kernel-doc
>> > processing, the further we dig ourselves into this hole.
>> > 
>> > If kernel-doc didn't have its own notion of section headers, such as
>> > "example:", we wouldn't have this problem to begin with. We could just
>> > use the usual rst construct; "example::" followed by an indented block.
>> > 
>> > I'm not going to stand in the way of the patch, but I'm telling you,
>> > this is going to get harder, not easier, on this path.
>> 
>> I agree with you in principle.  The problem, of course, is that this is a
>> legacy gift from before the RST days and it will be hard to change.
>> 
>> A quick grep shows that the pattern:
>> 
>> 	* Example:
>> 
>> appears nearly 100 times in current kernels.  It is not inconceivable to
>> make a push to get rid of all of those, turning them into ordinary RST
>> syntax - especially since not all of those are actually kerneldoc
>> comments.
>> 
>> The same quick grep says that "returns?:" appears about 10,000 times.
>> *That* will be painful to change, and I can only imagine that some
>> resistance would have to be overcome at some point.
>> 
>> So what do folks think we should do? :)
>
> 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 ;-)

Due to historical reasons, I think kernel-doc must handle a handful of
special cases, as a preprocessor converting old conventions to rst. The
title line, parameters, returns, and some in-line markup for &struct,
etc.

I'm not proposing changing "return:", because it's too widespread.

I *am* questioning everything else that necessitates adding *more*
special casing to handle things that would be easy to do in rst. I think
we should be moving in the other direction, fixing things by removing
special casing where we can. Case in point, "example:" as a section.

Why should we be adding different ways of doing things in the
documentation comments and the documentation files? Not having to do
that was one of the original goals. Unify stuff to one markup. Make
kernel-doc comments in source an extension to the documents under
Documentation/.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Graphics Center