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> <CAKXUXMwg7Vs5hm_X3ZHJj9309w5VYbnNeqXaajHBHS1oAKQydw@mail.gmail.com>
 <838a823b-f3fd-ed1b-70d1-82611f9f4ada@gmail.com>
In-Reply-To: <838a823b-f3fd-ed1b-70d1-82611f9f4ada@gmail.com>
From:   Lukas Bulwahn <lukas.bulwahn@gmail.com>
Date:   Fri, 12 Mar 2021 08:00:40 +0100
Message-ID: <CAKXUXMyJKU2ayx6KPFU50JA+t+X6-hhQwo0woNC18T6FTK60rw@mail.gmail.com>
Subject: Re: [RFC] scripts: kernel-doc: avoid warnings due to initial
 commented lines in file
To:     Aditya <yashsri421@gmail.com>
Cc:     Markus Heiser <markus.heiser@darmarit.de>,
        Jonathan Corbet <corbet@lwn.net>,
        "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 Thu, Mar 11, 2021 at 10:04 PM Aditya <yashsri421@gmail.com> wrote:
>
> On 10/3/21 11:49 am, Lukas Bulwahn wrote:
> > On Tue, Mar 9, 2021 at 10:24 PM Aditya <yashsri421@gmail.com> wrote:
> >>
> >> On 9/3/21 7:00 pm, Markus Heiser wrote:
> >>>
> >>> Am 09.03.21 um 13:53 schrieb Aditya Srivastava:
> >>>> Starting commented lines in a file mostly contains comments describing
> >>>> license, copyright or general information about the file.
> >>>>
> >>>> E.g., in sound/pci/ctxfi/ctresource.c, initial comment lines describe
> >>>> its copyright and other related file informations.
> >>>
> >>> 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.
> >>
> >
> > Aditya, can you provide a diff of the warnings over the whole kernel tree?
> >
> > At the moment, your patch just implements ignoring the initial
> > comment, which probably is good for experimentation.
> >
> > Alternatively, we could simply have a dedicated warning and then
> > ignore it or even warn and then parse it as-if.
> >
> > In the "long run", we would probably want to fix all current files in
> > the repository by just replacing '/**' by '/*' and have kernel-doc
> > warn about this suspicious pattern, when new files appear (maybe even
> > configurable, but that is another feature to enable or disable certain
> > kernel-doc checks and warnings). I would certainly assist and
> > contribute to such a clean-up task.
> >
> > I think the first step is to look at the diff, and see how many cases
> > really appear in the tree... then check how many patches throughout
> > the whole tree are required and if they are generally accepted.
> >
>
> Hi Lukas!
> This is the diff of the warnings over kernel tree before and after
> applying these changes.
> There are 2 sections in this report:
> 1) for the warnings present before, but not after, and;
> 2) after but not before
>
> The part (2) contains, for some cases, where the warning for "warning:
> Incorrect use of kernel-doc format:" type has changed to "warning:
> wrong kernel-doc identifier on line:" type.
>
> The diff file can be found at:
> https://github.com/AdityaSrivast/kernel-tasks/blob/master/random/kernel-doc/avoid_init_line_diff.txt
>

Thanks, let us check if we can use this diff to create a patch set
that cleans up those header comments for those files.

Lukas