Re: [PATCH v6 11/16] scripts: kernel-doc: validate kernel-doc markup with the actual names
From: Jonathan Corbet <corbet@lwn.net>
Date: 2021-01-18 20:37:35
Also in:
lkml
On Thu, 14 Jan 2021 09:04:47 +0100 Mauro Carvalho Chehab [off-list ref] 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@kernel.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