Re: [PATCH v6 11/16] scripts: kernel-doc: validate kernel-doc markup with the actual names
From: Mauro Carvalho Chehab
Date: Tue Jan 19 2021 - 02:47:20 EST
Em Mon, 18 Jan 2021 13:35:45 -0700
Jonathan Corbet <corbet@xxxxxxx> escreveu:
> 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.
Yeah, new warnings are unavoidable, as new patches may be introducing
extra issues. Hopefully, the new warning will help people to detect
the issue earlier before submitting upstream.