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;
Subject: Re: [PATCH] scripts: kernel-doc: add warning for comment not
 following kernel-doc syntax
To:     Jonathan Corbet <corbet@lwn.net>
Cc:     lukas.bulwahn@gmail.com,
        linux-kernel-mentees@lists.linuxfoundation.org,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
References: <20210329092945.13152-1-yashsri421@gmail.com>
 <87czvit65m.fsf@meer.lwn.net>
From:   Aditya Srivastava <yashsri421@gmail.com>
Message-ID: <a35096d5-99e7-6b69-c959-1136d511a0ff@gmail.com>
Date:   Mon, 29 Mar 2021 20:40:36 +0530
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101
 Thunderbird/68.10.0
MIME-Version: 1.0
In-Reply-To: <87czvit65m.fsf@meer.lwn.net>
Content-Type: text/plain; charset=utf-8
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Precedence: bulk

On 29/3/21 7:26 pm, Jonathan Corbet wrote:
> Aditya Srivastava <yashsri421@gmail.com> writes:
> 
>> Currently, kernel-doc start parsing the comment as a kernel-doc comment if
>> it starts with '/**', but does not take into account if the content inside
>> the comment too, adheres with the expected format.
>> This results in unexpected and unclear warnings for the user.
>>
>> E.g., running scripts/kernel-doc -none mm/memcontrol.c emits:
>> "mm/memcontrol.c:961: warning: expecting prototype for do not fallback to current(). Prototype was for get_mem_cgroup_from_current() instead"
>>
>> Here kernel-doc parses the corresponding comment as a kernel-doc comment
>> and expects prototype for it in the next lines, and as a result causing
>> this warning.
>>
>> Provide a clearer warning message to the users regarding the same, if the
>> content inside the comment does not follow the kernel-doc expected format.
>>
>> Signed-off-by: Aditya Srivastava <yashsri421@gmail.com>
>> ---
>>  scripts/kernel-doc | 17 +++++++++++++----
>>  1 file changed, 13 insertions(+), 4 deletions(-)
> 
> This is definitely a capability we want, but I really don't think that
> we can turn it on by default - for now.  Experience shows that if you
> create a blizzard of warnings, nobody sees any of them.  How many
> warnings does this add to a full docs build?
> 

Hi Jonathan, here's the diff I have created for the warnings before
and after the changes:
https://github.com/AdityaSrivast/kernel-tasks/blob/master/random/kernel-doc/kernel_doc_comment_syntax.txt

Around ~1320 new warnings of this type are added to the kernel tree,
and around ~1580 warnings are removed.

Thanks
Aditya

> For now I think we need a flag to turn this warning on, which perhaps
> can be set for a W=1 build.
> > Thanks,
> 
> jon
>