Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
MIME-Version: 1.0
References: <20210309125324.4456-1-yashsri421@gmail.com> <8959bf29-9ee1-6a1d-da18-f440232864f3@darmarit.de>
 <c673e76f-72db-bbee-39d6-f5428e765173@gmail.com> <871rcg2p8g.fsf@meer.lwn.net>
In-Reply-To: <871rcg2p8g.fsf@meer.lwn.net>
From:   Lukas Bulwahn <lukas.bulwahn@gmail.com>
Date:   Thu, 18 Mar 2021 11:55:05 +0100
Message-ID: <CAKXUXMzwTp1H_vokVEAJSnmm7jNHfWzhhmLfpcrrBD9b8ak+dA@mail.gmail.com>
Subject: Re: [RFC] scripts: kernel-doc: avoid warnings due to initial
 commented lines in file
To:     Jonathan Corbet <corbet@lwn.net>
Cc:     Aditya <yashsri421@gmail.com>,
        Markus Heiser <markus.heiser@darmarit.de>,
        "open list:DOCUMENTATION" <linux-doc@vger.kernel.org>,
        Linux Kernel Mailing List <linux-kernel@vger.kernel.org>,
        linux-kernel-mentees@lists.linuxfoundation.org
Content-Type: text/plain; charset="UTF-8"
Precedence: bulk

On Mon, Mar 15, 2021 at 8:25 PM Jonathan Corbet <corbet@lwn.net> wrote:
>
> Aditya <yashsri421@gmail.com> writes:
>
> >> The opening comment mark /** is used for kernel-doc comments [1]
> >>
> >> [1]
> >> https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#how-to-format-kernel-doc-comments
> >>
> >
> > Hi Markus!
> > That's true. But the content inside the comment does not follow
> > kernel-doc format.
> > For e.g., try running kernel-doc -none/man/rst on the above file in
> > the example("sound/pci/ctxfi/ctresource.c").
> > The starting 2-3 lines in files generally do not contain any
> > struct/enum/function, etc. declaration.
>
> The problem is that it's marked as a kerneldoc comment without actually
> being one; it looks like somebody's internal corporate formatting.  The
> fix is not to put a hack into kernel-doc - we have more than enough of
> those in the file already!  The right thing to do is to remove the extra
> "*" so that the comment doesn't look like a kerneldoc comment anymore.
>

Jonathan, I agree that that is the right thing to do. Aditya is
already following through and is cleaning up the repository. So, let
us be optimistic that we will have cleaned up all of those occurrences
within a few weeks. But how to continue? Someone is going to come with
new files and introduce this pattern again in the repository; and as
of now, we do not have a script to identify that pattern and react...

Running kernel-doc on the whole tree continuously and just observing
the new warnings is probably not going to work as of now: there are
20,000 kernel-doc warnings and at least, I cannot see a really good
way to filter out this one specific type of issue among all the
warnings that will might appear in the future (without specifically
applying Aditya's patch and looking at the diff before and after).

I wonder if we could extend kernel-doc (not your preferred option as
it seems) for a new dedicated warning message or maintain a separate
kernel-doc sanity checking script to emit a dedicated warning based on
some heuristics that suggests when a "header comment" is probably
unintentionally declared as a "kernel-doc comment" when it really
should not be.

Jonathan, would you then prefer to have a separate kernel-doc sanity
checking script that then allows us to maintain checking for patterns
we already cleaned up?

Eventually, we might have cleaned up enough to just use kernel-doc and
keep it kind of warning-free (as with make htmldocs now) and then, we
can simply follow up with kernel-doc and some basic monitoring
scripts, but with 20,000 warnings in the whole repository to start
with, it is still a long way to that point, IMHO.

Lukas