| Message ID | 20200625064619.2775707-2-lee.jones@linaro.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [01/10] mfd: wm8350-core: Supply description wm8350_reg_{un}lock args | expand |
On Thu, Jun 25, 2020 at 07:46:10AM +0100, Lee Jones wrote: > Kerneldoc syntax is used, but not complete. Descriptions required. > > Prevents warnings like: > > drivers/mfd/wm8350-core.c:136: warning: Function parameter or member 'wm8350' not described in 'wm8350_reg_lock' > drivers/mfd/wm8350-core.c:165: warning: Function parameter or member 'wm8350' not described in 'wm8350_reg_unlock' > > Cc: <stable@vger.kernel.org> > Cc: patches@opensource.cirrus.com > Signed-off-by: Lee Jones <lee.jones@linaro.org> > --- > drivers/mfd/wm8350-core.c | 4 ++++ > 1 file changed, 4 insertions(+) > > diff --git a/drivers/mfd/wm8350-core.c b/drivers/mfd/wm8350-core.c > index 42b16503e6cd1..fbc77b218215c 100644 > --- a/drivers/mfd/wm8350-core.c > +++ b/drivers/mfd/wm8350-core.c > @@ -131,6 +131,8 @@ EXPORT_SYMBOL_GPL(wm8350_block_write); > * The WM8350 has a hardware lock which can be used to prevent writes to > * some registers (generally those which can cause particularly serious > * problems if misused). This function enables that lock. > + * > + * @wm8350: pointer to local driver data structure > */ > int wm8350_reg_lock(struct wm8350 *wm8350) > { > @@ -160,6 +162,8 @@ EXPORT_SYMBOL_GPL(wm8350_reg_lock); > * problems if misused). This function disables that lock so updates > * can be performed. For maximum safety this should be done only when > * required. > + * > + * @wm8350: pointer to local driver data structure > */ > int wm8350_reg_unlock(struct wm8350 *wm8350) > { > -- > 2.25.1 > Why are all of these documentation fixes for stable?
On Thu, 25 Jun 2020, Greg KH wrote: > On Thu, Jun 25, 2020 at 07:46:10AM +0100, Lee Jones wrote: > > Kerneldoc syntax is used, but not complete. Descriptions required. > > > > Prevents warnings like: > > > > drivers/mfd/wm8350-core.c:136: warning: Function parameter or member 'wm8350' not described in 'wm8350_reg_lock' > > drivers/mfd/wm8350-core.c:165: warning: Function parameter or member 'wm8350' not described in 'wm8350_reg_unlock' > > > > Cc: <stable@vger.kernel.org> > > Cc: patches@opensource.cirrus.com > > Signed-off-by: Lee Jones <lee.jones@linaro.org> > > --- > > drivers/mfd/wm8350-core.c | 4 ++++ > > 1 file changed, 4 insertions(+) > > > > diff --git a/drivers/mfd/wm8350-core.c b/drivers/mfd/wm8350-core.c > > index 42b16503e6cd1..fbc77b218215c 100644 > > --- a/drivers/mfd/wm8350-core.c > > +++ b/drivers/mfd/wm8350-core.c > > @@ -131,6 +131,8 @@ EXPORT_SYMBOL_GPL(wm8350_block_write); > > * The WM8350 has a hardware lock which can be used to prevent writes to > > * some registers (generally those which can cause particularly serious > > * problems if misused). This function enables that lock. > > + * > > + * @wm8350: pointer to local driver data structure > > */ > > int wm8350_reg_lock(struct wm8350 *wm8350) > > { > > @@ -160,6 +162,8 @@ EXPORT_SYMBOL_GPL(wm8350_reg_lock); > > * problems if misused). This function disables that lock so updates > > * can be performed. For maximum safety this should be done only when > > * required. > > + * > > + * @wm8350: pointer to local driver data structure > > */ > > int wm8350_reg_unlock(struct wm8350 *wm8350) > > { > > Why are all of these documentation fixes for stable? Because they fix compiler warnings. Not correct?
On Thu, Jun 25, 2020 at 08:13:13AM +0100, Lee Jones wrote: > On Thu, 25 Jun 2020, Greg KH wrote: > > > On Thu, Jun 25, 2020 at 07:46:10AM +0100, Lee Jones wrote: > > > Kerneldoc syntax is used, but not complete. Descriptions required. > > > > > > Prevents warnings like: > > > > > > drivers/mfd/wm8350-core.c:136: warning: Function parameter or member 'wm8350' not described in 'wm8350_reg_lock' > > > drivers/mfd/wm8350-core.c:165: warning: Function parameter or member 'wm8350' not described in 'wm8350_reg_unlock' > > > > > > Cc: <stable@vger.kernel.org> > > > Cc: patches@opensource.cirrus.com > > > Signed-off-by: Lee Jones <lee.jones@linaro.org> > > > --- > > > drivers/mfd/wm8350-core.c | 4 ++++ > > > 1 file changed, 4 insertions(+) > > > > > > diff --git a/drivers/mfd/wm8350-core.c b/drivers/mfd/wm8350-core.c > > > index 42b16503e6cd1..fbc77b218215c 100644 > > > --- a/drivers/mfd/wm8350-core.c > > > +++ b/drivers/mfd/wm8350-core.c > > > @@ -131,6 +131,8 @@ EXPORT_SYMBOL_GPL(wm8350_block_write); > > > * The WM8350 has a hardware lock which can be used to prevent writes to > > > * some registers (generally those which can cause particularly serious > > > * problems if misused). This function enables that lock. > > > + * > > > + * @wm8350: pointer to local driver data structure > > > */ > > > int wm8350_reg_lock(struct wm8350 *wm8350) > > > { > > > @@ -160,6 +162,8 @@ EXPORT_SYMBOL_GPL(wm8350_reg_lock); > > > * problems if misused). This function disables that lock so updates > > > * can be performed. For maximum safety this should be done only when > > > * required. > > > + * > > > + * @wm8350: pointer to local driver data structure > > > */ > > > int wm8350_reg_unlock(struct wm8350 *wm8350) > > > { > > > > Why are all of these documentation fixes for stable? > > Because they fix compiler warnings. When you type 'make' these warnings show up? We don't do documentation builds as part of a normal build... If for some reason we ever get rid of all of the thousands of current warnings, then yes, I will be glad to consider stuff like this then. thanks, greg k-h
On Thu, 25 Jun 2020 08:13:13 +0100 Lee Jones <lee.jones@linaro.org> wrote: > > Why are all of these documentation fixes for stable? > > Because they fix compiler warnings. > > Not correct? I am overjoyed to see people fixing docs build warnings, it is work that is desperately needed. That said, these warning fixes are probably not stable material; the problem is bigger and longer-term than that. Thanks, jon
On Thu, 25 Jun 2020, Greg KH wrote: > On Thu, Jun 25, 2020 at 08:13:13AM +0100, Lee Jones wrote: > > On Thu, 25 Jun 2020, Greg KH wrote: > > > > > On Thu, Jun 25, 2020 at 07:46:10AM +0100, Lee Jones wrote: > > > > Kerneldoc syntax is used, but not complete. Descriptions required. > > > > > > > > Prevents warnings like: > > > > > > > > drivers/mfd/wm8350-core.c:136: warning: Function parameter or member 'wm8350' not described in 'wm8350_reg_lock' > > > > drivers/mfd/wm8350-core.c:165: warning: Function parameter or member 'wm8350' not described in 'wm8350_reg_unlock' > > > > > > > > Cc: <stable@vger.kernel.org> > > > > Cc: patches@opensource.cirrus.com > > > > Signed-off-by: Lee Jones <lee.jones@linaro.org> > > > > --- > > > > drivers/mfd/wm8350-core.c | 4 ++++ > > > > 1 file changed, 4 insertions(+) > > > > > > > > diff --git a/drivers/mfd/wm8350-core.c b/drivers/mfd/wm8350-core.c > > > > index 42b16503e6cd1..fbc77b218215c 100644 > > > > --- a/drivers/mfd/wm8350-core.c > > > > +++ b/drivers/mfd/wm8350-core.c > > > > @@ -131,6 +131,8 @@ EXPORT_SYMBOL_GPL(wm8350_block_write); > > > > * The WM8350 has a hardware lock which can be used to prevent writes to > > > > * some registers (generally those which can cause particularly serious > > > > * problems if misused). This function enables that lock. > > > > + * > > > > + * @wm8350: pointer to local driver data structure > > > > */ > > > > int wm8350_reg_lock(struct wm8350 *wm8350) > > > > { > > > > @@ -160,6 +162,8 @@ EXPORT_SYMBOL_GPL(wm8350_reg_lock); > > > > * problems if misused). This function disables that lock so updates > > > > * can be performed. For maximum safety this should be done only when > > > > * required. > > > > + * > > > > + * @wm8350: pointer to local driver data structure > > > > */ > > > > int wm8350_reg_unlock(struct wm8350 *wm8350) > > > > { > > > > > > Why are all of these documentation fixes for stable? > > > > Because they fix compiler warnings. > > When you type 'make' these warnings show up? We don't do documentation > builds as part of a normal build... 'make W=1' yes. :) > If for some reason we ever get rid of all of the thousands of current > warnings, then yes, I will be glad to consider stuff like this then. Workin' on it! Sorry for the noise (for now).
On Thu, 25 Jun 2020, Jonathan Corbet wrote: > On Thu, 25 Jun 2020 08:13:13 +0100 > Lee Jones <lee.jones@linaro.org> wrote: > > > > Why are all of these documentation fixes for stable? > > > > Because they fix compiler warnings. > > > > Not correct? > > I am overjoyed to see people fixing docs build warnings, it is work that > is desperately needed. I'll do what I can with the time that I have. The plan is to keep plodding on and seeing how far I can take it. A clean W=1 build sounds like rainbows and unicorns presently, but Rome wasn't built in a day. Tell you the truth, drafting patches (again, after a break) is a welcome change/release from digging around and reviewing Android Stable patches. It's the only thing keeping me sane. :) > That said, these warning fixes are probably not > stable material; the problem is bigger and longer-term than that. Fair enough.
diff --git a/drivers/mfd/wm8350-core.c b/drivers/mfd/wm8350-core.c index 42b16503e6cd1..fbc77b218215c 100644 --- a/drivers/mfd/wm8350-core.c +++ b/drivers/mfd/wm8350-core.c @@ -131,6 +131,8 @@ EXPORT_SYMBOL_GPL(wm8350_block_write); * The WM8350 has a hardware lock which can be used to prevent writes to * some registers (generally those which can cause particularly serious * problems if misused). This function enables that lock. + * + * @wm8350: pointer to local driver data structure */ int wm8350_reg_lock(struct wm8350 *wm8350) { @@ -160,6 +162,8 @@ EXPORT_SYMBOL_GPL(wm8350_reg_lock); * problems if misused). This function disables that lock so updates * can be performed. For maximum safety this should be done only when * required. + * + * @wm8350: pointer to local driver data structure */ int wm8350_reg_unlock(struct wm8350 *wm8350) {
Kerneldoc syntax is used, but not complete. Descriptions required. Prevents warnings like: drivers/mfd/wm8350-core.c:136: warning: Function parameter or member 'wm8350' not described in 'wm8350_reg_lock' drivers/mfd/wm8350-core.c:165: warning: Function parameter or member 'wm8350' not described in 'wm8350_reg_unlock' Cc: <stable@vger.kernel.org> Cc: patches@opensource.cirrus.com Signed-off-by: Lee Jones <lee.jones@linaro.org> --- drivers/mfd/wm8350-core.c | 4 ++++ 1 file changed, 4 insertions(+)