linux-kernel - Re: [PATCH v6 11/16] scripts: 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: <20210118133545.05af2277@lwn.net>
Date:   Mon, 18 Jan 2021 13:35:45 -0700
From:   Jonathan Corbet <corbet@....net>
To:     Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Cc:     Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH v6 11/16] scripts: kernel-doc: validate kernel-doc
 markup with the actual names

On Thu, 14 Jan 2021 09:04:47 +0100
Mauro Carvalho Chehab <mchehab+huawei@...nel.org> wrote:

> Kernel-doc currently expects that the kernel-doc markup to come
> just before the function/enum/struct/union/typedef prototype.
> 
> Yet, if it find things like:
> 
> 	/**
> 	 * refcount_add - add a value to a refcount
> 	 * @i: the value to add to the refcount
> 	 * @r: the refcount
> 	 */
> 	static inline void __refcount_add(int i, refcount_t *r, int *oldp);
> 	static inline void refcount_add(int i, refcount_t *r);
> 
> Kernel-doc will do the wrong thing:
> 
> 	foobar.h:6: warning: Function parameter or member 'oldp' not described in '__refcount_add'
> 	.. c:function:: void __refcount_add (int i, refcount_t *r, int *oldp)
> 
> 	   add a value to a refcount
> 
> 	**Parameters**
> 
> 	``int i``
> 	  the value to add to the refcount
> 
> 	``refcount_t *r``
> 	  the refcount
> 
> 	``int *oldp``
> 	  *undescribed*
> 
> Basically, it will document "__refcount_add" with the kernel-doc
> markup for refcount_add.
> 
> If both functions have the same arguments, this won't even
> produce any warning!
> 
> Add a logic to check if the kernel-doc identifier matches the actual
> name of the C function or data structure that will be documented.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>

I've applied this one; it seems useful to have even if it creates more
warnings that Stephen will duly email me about tomorrow...:)  I have parts
1-10 set aside and will apply any that don't get picked up directly by the
maintainers involved.

Thanks,

jon