linux-kernel - Re: [PATCH v3 56/56] scrpits: kernel-doc: validate kernel-doc markup with the actual names

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20201105081526.1f9c7f4a@lwn.net>
Date:   Thu, 5 Nov 2020 08:15:26 -0700
From:   Jonathan Corbet <corbet@....net>
To:     Matthew Wilcox <willy@...radead.org>
Cc:     Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH v3 56/56] scrpits: kernel-doc: validate kernel-doc
 markup with the actual names

On Thu, 5 Nov 2020 15:00:17 +0000
Matthew Wilcox <willy@...radead.org> wrote:

> I wonder if we could change kernel-doc to be (optionally) less verbose.
> If we allowed people to write:
> 
> /**
>  * Add a value to a refcount.
>  * @i: The value to add to the refcount
>  * @r: The refcount
>  */
> 
> and had the kernel-doc script pick up the name of the following function
> automatically, would that be an improvement we could all agree on?

Given the number of issues Mauro just fixed where the comments had become
separated from the functions they documented, this seems potentially
hazardous...  It seems especially likely to fail with the "change foo() to
__foo() and add a new foo() down below" pattern that is fairly common.

jon