diff mbox series

[01/10] mfd: wm8350-core: Supply description wm8350_reg_{un}lock args

Message ID 20200625064619.2775707-2-lee.jones@linaro.org
State Accepted
Commit afb718a870ef20efcf18d6fbea45fa6576a54d27
Headers show
Series [01/10] mfd: wm8350-core: Supply description wm8350_reg_{un}lock args | expand

Commit Message

Lee Jones June 25, 2020, 6:46 a.m. UTC
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(+)

-- 
2.25.1

Comments

Greg KH June 25, 2020, 6:56 a.m. UTC | #1
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?
Lee Jones June 25, 2020, 7:13 a.m. UTC | #2
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?

-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog
Greg KH June 25, 2020, 9:45 a.m. UTC | #3
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
Jonathan Corbet June 25, 2020, 1:24 p.m. UTC | #4
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
Lee Jones June 25, 2020, 1:34 p.m. UTC | #5
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).

-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog
Lee Jones June 25, 2020, 1:38 p.m. UTC | #6
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.

-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog
diff mbox series

Patch

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)
 {