linux-doc.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Jani Nikula <jani.nikula@linux.intel.com>
To: Matthew Wilcox <willy@infradead.org>, Jonathan Corbet <corbet@lwn.net>
Cc: 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: Tue, 31 Mar 2020 13:50:11 +0300	[thread overview]
Message-ID: <87zhbwg5ng.fsf@intel.com> (raw)
In-Reply-To: <20200327165022.GP22483@bombadil.infradead.org>

On Fri, 27 Mar 2020, Matthew Wilcox <willy@infradead.org> 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@linux.intel.com> 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

  parent reply	other threads:[~2020-03-31 10:50 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 [this message]
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=87zhbwg5ng.fsf@intel.com \
    --to=jani.nikula@linux.intel.com \
    --cc=corbet@lwn.net \
    --cc=gregkh@linuxfoundation.org \
    --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).