Received-SPF: softfail (google.com: domain of transitioning linux-kernel-owner@vger.kernel.org does not designate 23.128.96.19 as permitted sender) client-ip=23.128.96.19;
Date:   Wed, 23 Feb 2022 13:55:48 +0100
From:   Tomasz =?UTF-8?B?V2FybmllxYLFgm8=?= <tomasz.warniello@gmail.com>
To:     Akira Yokosawa <akiyks@gmail.com>
Cc:     Randy Dunlap <rdunlap@infradead.org>, corbet@lwn.net,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        tomasz.warniello@gmail.com
Subject: Re: [PATCH v4 00/11] Transform documentation into POD
Message-ID: <20220223135548.27babd85@fuji.fritz.box>
In-Reply-To: <939ef119-8a84-9206-bd7c-cfd215bb0200@gmail.com>
References: <525f3696-91f4-5a4a-c9ef-24758ccaa2bb@infradead.org>
        <ff98f455-0221-7ff0-08ed-8dea9f08694b@gmail.com>
        <939ef119-8a84-9206-bd7c-cfd215bb0200@gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Precedence: bulk

Hi Akira,

Take a look at `man perl` and you will find a synopsis also. It's simply
better in depicting grammar relations than a flat switch list. Especially
when the grammar gets complex. I dislike it also. And I don't think it
looks good. Rather creepy and overwhelming.

> > I don't see much point for such a non-user-facing script having nice-looking
> > well-structured documentation in the first place.

You're touching the very essence of kernel-doc here. What and who is it for?
Not just the script - all of it.

Regards,

Tomasz