On Thu, 14 Jan 2021 09:04:47 +0100 Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> 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@xxxxxxxxxx> 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
