Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   Jonathan Corbet <corbet@lwn.net>
To:     Tomasz =?utf-8?B?V2FybmllxYLFgm8=?= <tomasz.warniello@gmail.com>
Cc:     linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        Tomasz =?utf-8?B?V2FybmllxYLFgm8=?= <tomasz.warniello@gmail.com>
Subject: Re: [RFC] scripts: kernel-doc: Major kernel-doc rework
In-Reply-To: <20220205233945.7a4d22d8@fuji.fritz.box>
References: <20220205233945.7a4d22d8@fuji.fritz.box>
Date:   Wed, 16 Feb 2022 16:45:25 -0700
Message-ID: <8735ki2x62.fsf@meer.lwn.net>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
Precedence: bulk

Tomasz Warnie=C5=82=C5=82o <tomasz.warniello@gmail.com> writes:

> This is in fact a release notification of a major kernel-doc script
> refurbishment I have done. My work has reached a stage, which can be
> considered a world sync point and here we are.
>
> I'm not sending all the patches to the Linux mailing list, as I prefer
> to check what you think before I emit about 500 emails.
>
> I've parked the lot for you to inspect here:
> https://salsa.debian.org/guest/kernel-doc
>
> This also helps me report the bug fixes. See the issue tracker:
> https://salsa.debian.org/guest/kernel-doc/-/issues

I've taken a quick look - that's a lot of stuff.  Thanks for not sending
it all; you would have gotten some unhappy answers.

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.

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

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

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

See what I'm getting at?

Thanks,

jon