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;
From:   Jonathan Corbet <corbet@lwn.net>
To:     Aditya <yashsri421@gmail.com>,
        Markus Heiser <markus.heiser@darmarit.de>
Cc:     lukas.bulwahn@gmail.com, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org,
        linux-kernel-mentees@lists.linuxfoundation.org
Subject: Re: [RFC] scripts: kernel-doc: avoid warnings due to initial
 commented lines in file
In-Reply-To: <c673e76f-72db-bbee-39d6-f5428e765173@gmail.com>
References: <20210309125324.4456-1-yashsri421@gmail.com>
 <8959bf29-9ee1-6a1d-da18-f440232864f3@darmarit.de>
 <c673e76f-72db-bbee-39d6-f5428e765173@gmail.com>
Date:   Mon, 15 Mar 2021 13:25:51 -0600
Message-ID: <871rcg2p8g.fsf@meer.lwn.net>
MIME-Version: 1.0
Content-Type: text/plain
Precedence: bulk

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.

Thanks,

jon