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] [day] [month] [year] [list]

Message-ID: <20201105153029.GM17076@casper.infradead.org>
Date:   Thu, 5 Nov 2020 15:30:29 +0000
From:   Matthew Wilcox <willy@...radead.org>
To:     Jonathan Corbet <corbet@....net>
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, Nov 05, 2020 at 08:15:26AM -0700, Jonathan Corbet wrote:
> 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.

Sort of, yes.  The usual case for doing that is where one adds a new
parameter, and kernel-doc will warn about that.  But if the parameters
stay the same (eg refcount_add takes a lock and __refcount_add assumes
the lock is already held), then you've got documentation of __refcount_add
and no documentation of refcount_add() ... and it's probably still _true_
documentation, just not as useful.