Re: [RFC] scripts: kernel-doc: Major kernel-doc rework

["Tomasz Warniełło" <tomasz.warniello@gmail.com>]

On Wed, 16 Feb 2022 16:45:25 -0700
Jonathan Corbet <corbet@lwn.net> wrote:

> Some overall thoughts:
> 
>  - Work like this needs to be broken up into digestible batches.  Let's
>    start with the POD stuff that I've (finally) commented on; other
>    stuff can come later.

I will prepare the POD part. As for the rest, you will need a porter if you
decide this is the way to go. I could help with explanations if something is
unclear and as long as the questions come soon. The winter is almost over and
I need to switch to other activities like earning money.

>  - The coding style in the new work is very unkernellike; that will make
>    it harder to get this work merged.

Yes. I can only add a thought: it seems unnatural to me to have the same style
for various languages.

>  - But let's take a step back and ask: why are we doing all of this work
>    in the first place?  What is the benefit to the kernel community from
>    all this churn, and a growth of the kernel-doc script by over 2,000
>    lines (even if an awful lot of them are blank)?

My motivation was just climbing this mountain, nothing else. I don't even
know, how important this script is to whom. I can only guess. Neither am I
a C programmer, nor want to become one. So this question is to another part
of the community.

I could though think of the benefits to the maintainers. In this respect I've
moved things forward quite a bit, I gather.

As for the blank lines, they are just one character each and trivial to get
rid of.

> I'm serious about that last question; do we really want to invest that
> kind of effort into this nasty old script?  Or, if we're going to do
> such a thing, should we maybe start with Markus's rewrite into Python
> instead?  If we're going to thrash the code and make it unrecognizable,
> perhaps we should move to a language that is consistent with the rest of
> the docs build system and which, I believe, is easier for more kernel
> developers to deal with?

I understand. I didn't know there was a rewrite. I'm not into Python, but
if you could post a link, I'd take a look out of curiosity.

If the community prefers Python, what can I say about this? Their choice.

Personally, I'd rather play with translating this script to Raku (aka Perl 6).
I also wonder, how Perl 5 will transition to Perl 7. A question to Perl
experts.

> I am *not* saying that this work cannot be accepted, and I certainly do
> not want to alienate somebody who is actually able to look at kernel-doc
> and not have their eyes bleed out.  But I am saying that, before
> launching into a hundreds-of-patches journey, we should know where we're
> going and why we are doing it.

I agree.

> See what I'm getting at?

Yes. Thanks.

Tomasz