[20/25] pinctrl: pinctrl-rza1: Demote some kerneldoc headers and fix others

Message ID 20200713144930.1034632-21-lee.jones@linaro.org
State Accepted
Commit 6d31fa6aea09b3714c7a0a27d8cad3639c5f54ff
Headers show
Series
  • Rid W=1 warnings in Pinctrl
Related show

Commit Message

Lee Jones July 13, 2020, 2:49 p.m.
Some description blocks are void of any description/documentation,
others are missing 'struct' identifiers, there are also a couple of
misspellings of function parameter names.  Fix all of them.

Fixes the following W=1 kernel build warning(s):

 drivers/pinctrl/pinctrl-rza1.c:81: warning: cannot understand function prototype: 'struct rza1_bidir_pin '
 drivers/pinctrl/pinctrl-rza1.c:90: warning: cannot understand function prototype: 'struct rza1_bidir_entry '
 drivers/pinctrl/pinctrl-rza1.c:98: warning: cannot understand function prototype: 'struct rza1_swio_pin '
 drivers/pinctrl/pinctrl-rza1.c:108: warning: cannot understand function prototype: 'struct rza1_swio_entry '
 drivers/pinctrl/pinctrl-rza1.c:116: warning: cannot understand function prototype: 'struct rza1_pinmux_conf '
 drivers/pinctrl/pinctrl-rza1.c:443: warning: cannot understand function prototype: 'struct rza1_mux_conf '
 drivers/pinctrl/pinctrl-rza1.c:462: warning: cannot understand function prototype: 'struct rza1_port '
 drivers/pinctrl/pinctrl-rza1.c:482: warning: cannot understand function prototype: 'struct rza1_pinctrl '
 drivers/pinctrl/pinctrl-rza1.c:546: warning: Function parameter or member 'port' not described in 'rza1_pinmux_get_flags'
 drivers/pinctrl/pinctrl-rza1.c:546: warning: Function parameter or member 'pin' not described in 'rza1_pinmux_get_flags'
 drivers/pinctrl/pinctrl-rza1.c:546: warning: Function parameter or member 'func' not described in 'rza1_pinmux_get_flags'
 drivers/pinctrl/pinctrl-rza1.c:546: warning: Function parameter or member 'rza1_pctl' not described in 'rza1_pinmux_get_flags'
 drivers/pinctrl/pinctrl-rza1.c:575: warning: Function parameter or member 'port' not described in 'rza1_set_bit'
 drivers/pinctrl/pinctrl-rza1.c:575: warning: Function parameter or member 'reg' not described in 'rza1_set_bit'
 drivers/pinctrl/pinctrl-rza1.c:575: warning: Function parameter or member 'bit' not described in 'rza1_set_bit'
 drivers/pinctrl/pinctrl-rza1.c:575: warning: Function parameter or member 'set' not described in 'rza1_set_bit'
 drivers/pinctrl/pinctrl-rza1.c:672: warning: Function parameter or member 'rza1_pctl' not described in 'rza1_pin_mux_single'
 drivers/pinctrl/pinctrl-rza1.c:672: warning: Excess function parameter 'pinctrl' description in 'rza1_pin_mux_single'

Cc: Geert Uytterhoeven <geert+renesas@glider.be>
Cc: Jacopo Mondi <jacopo+renesas@jmondi.org>
Cc: linux-renesas-soc@vger.kernel.org
Signed-off-by: Lee Jones <lee.jones@linaro.org>

---
 drivers/pinctrl/pinctrl-rza1.c | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

-- 
2.25.1

Comments

Jacopo Mondi July 14, 2020, 1:14 p.m. | #1
Hi Lee,

On Mon, Jul 13, 2020 at 03:49:25PM +0100, Lee Jones wrote:
> Some description blocks are void of any description/documentation,

> others are missing 'struct' identifiers, there are also a couple of

> misspellings of function parameter names.  Fix all of them.

>

> Fixes the following W=1 kernel build warning(s):

>

>  drivers/pinctrl/pinctrl-rza1.c:81: warning: cannot understand function prototype: 'struct rza1_bidir_pin '

>  drivers/pinctrl/pinctrl-rza1.c:90: warning: cannot understand function prototype: 'struct rza1_bidir_entry '

>  drivers/pinctrl/pinctrl-rza1.c:98: warning: cannot understand function prototype: 'struct rza1_swio_pin '

>  drivers/pinctrl/pinctrl-rza1.c:108: warning: cannot understand function prototype: 'struct rza1_swio_entry '

>  drivers/pinctrl/pinctrl-rza1.c:116: warning: cannot understand function prototype: 'struct rza1_pinmux_conf '

>  drivers/pinctrl/pinctrl-rza1.c:443: warning: cannot understand function prototype: 'struct rza1_mux_conf '

>  drivers/pinctrl/pinctrl-rza1.c:462: warning: cannot understand function prototype: 'struct rza1_port '

>  drivers/pinctrl/pinctrl-rza1.c:482: warning: cannot understand function prototype: 'struct rza1_pinctrl '

>  drivers/pinctrl/pinctrl-rza1.c:546: warning: Function parameter or member 'port' not described in 'rza1_pinmux_get_flags'

>  drivers/pinctrl/pinctrl-rza1.c:546: warning: Function parameter or member 'pin' not described in 'rza1_pinmux_get_flags'

>  drivers/pinctrl/pinctrl-rza1.c:546: warning: Function parameter or member 'func' not described in 'rza1_pinmux_get_flags'

>  drivers/pinctrl/pinctrl-rza1.c:546: warning: Function parameter or member 'rza1_pctl' not described in 'rza1_pinmux_get_flags'

>  drivers/pinctrl/pinctrl-rza1.c:575: warning: Function parameter or member 'port' not described in 'rza1_set_bit'

>  drivers/pinctrl/pinctrl-rza1.c:575: warning: Function parameter or member 'reg' not described in 'rza1_set_bit'

>  drivers/pinctrl/pinctrl-rza1.c:575: warning: Function parameter or member 'bit' not described in 'rza1_set_bit'

>  drivers/pinctrl/pinctrl-rza1.c:575: warning: Function parameter or member 'set' not described in 'rza1_set_bit'

>  drivers/pinctrl/pinctrl-rza1.c:672: warning: Function parameter or member 'rza1_pctl' not described in 'rza1_pin_mux_single'

>  drivers/pinctrl/pinctrl-rza1.c:672: warning: Excess function parameter 'pinctrl' description in 'rza1_pin_mux_single'

>

> Cc: Geert Uytterhoeven <geert+renesas@glider.be>

> Cc: Jacopo Mondi <jacopo+renesas@jmondi.org>

> Cc: linux-renesas-soc@vger.kernel.org

> Signed-off-by: Lee Jones <lee.jones@linaro.org>


Thanks, at the time I had no real idea about the implications of
documenting with kerneldoc :)

Acked-by: Jacopo Mondi <jacopo@jmondi.org>


Thanks
  j

> ---

>  drivers/pinctrl/pinctrl-rza1.c | 24 ++++++++++++------------

>  1 file changed, 12 insertions(+), 12 deletions(-)

>

> diff --git a/drivers/pinctrl/pinctrl-rza1.c b/drivers/pinctrl/pinctrl-rza1.c

> index 38a14bbced5f6..511f232ab7bc2 100644

> --- a/drivers/pinctrl/pinctrl-rza1.c

> +++ b/drivers/pinctrl/pinctrl-rza1.c

> @@ -75,7 +75,7 @@

>   * RZ/A1 pinmux flags

>   */

>

> -/**

> +/*

>   * rza1_bidir_pin - describe a single pin that needs bidir flag applied.

>   */

>  struct rza1_bidir_pin {

> @@ -83,7 +83,7 @@ struct rza1_bidir_pin {

>  	u8 func: 4;

>  };

>

> -/**

> +/*

>   * rza1_bidir_entry - describe a list of pins that needs bidir flag applied.

>   *		      Each struct rza1_bidir_entry describes a port.

>   */

> @@ -92,7 +92,7 @@ struct rza1_bidir_entry {

>  	const struct rza1_bidir_pin *pins;

>  };

>

> -/**

> +/*

>   * rza1_swio_pin - describe a single pin that needs swio flag applied.

>   */

>  struct rza1_swio_pin {

> @@ -102,7 +102,7 @@ struct rza1_swio_pin {

>  	u16 input: 1;

>  };

>

> -/**

> +/*

>   * rza1_swio_entry - describe a list of pins that needs swio flag applied

>   */

>  struct rza1_swio_entry {

> @@ -110,7 +110,7 @@ struct rza1_swio_entry {

>  	const struct rza1_swio_pin *pins;

>  };

>

> -/**

> +/*

>   * rza1_pinmux_conf - group together bidir and swio pinmux flag tables

>   */

>  struct rza1_pinmux_conf {

> @@ -431,7 +431,7 @@ static const struct rza1_pinmux_conf rza1l_pmx_conf = {

>   * RZ/A1 types

>   */

>  /**

> - * rza1_mux_conf - describes a pin multiplexing operation

> + * struct rza1_mux_conf - describes a pin multiplexing operation

>   *

>   * @id: the pin identifier from 0 to RZA1_NPINS

>   * @port: the port where pin sits on

> @@ -450,7 +450,7 @@ struct rza1_mux_conf {

>  };

>

>  /**

> - * rza1_port - describes a pin port

> + * struct rza1_port - describes a pin port

>   *

>   * This is mostly useful to lock register writes per-bank and not globally.

>   *

> @@ -467,12 +467,12 @@ struct rza1_port {

>  };

>

>  /**

> - * rza1_pinctrl - RZ pincontroller device

> + * struct rza1_pinctrl - RZ pincontroller device

>   *

>   * @dev: parent device structure

>   * @mutex: protect [pinctrl|pinmux]_generic functions

>   * @base: logical address base

> - * @nports: number of pin controller ports

> + * @nport: number of pin controller ports

>   * @ports: pin controller banks

>   * @pins: pin array for pinctrl core

>   * @desc: pincontroller desc for pinctrl core

> @@ -536,7 +536,7 @@ static inline int rza1_pinmux_get_swio(unsigned int port,

>  	return -ENOENT;

>  }

>

> -/**

> +/*

>   * rza1_pinmux_get_flags() - return pinmux flags associated to a pin

>   */

>  static unsigned int rza1_pinmux_get_flags(unsigned int port, unsigned int pin,

> @@ -566,7 +566,7 @@ static unsigned int rza1_pinmux_get_flags(unsigned int port, unsigned int pin,

>   * RZ/A1 SoC operations

>   */

>

> -/**

> +/*

>   * rza1_set_bit() - un-locked set/clear a single bit in pin configuration

>   *		    registers

>   */

> @@ -664,7 +664,7 @@ static inline int rza1_pin_get(struct rza1_port *port, unsigned int pin)

>  /**

>   * rza1_pin_mux_single() - configure pin multiplexing on a single pin

>   *

> - * @pinctrl: RZ/A1 pin controller device

> + * @rza1_pctl: RZ/A1 pin controller device

>   * @mux_conf: pin multiplexing descriptor

>   */

>  static int rza1_pin_mux_single(struct rza1_pinctrl *rza1_pctl,

> --

> 2.25.1

>
Lee Jones July 14, 2020, 1:45 p.m. | #2
On Tue, 14 Jul 2020, Jacopo Mondi wrote:

> Hi Lee,

> 

> On Mon, Jul 13, 2020 at 03:49:25PM +0100, Lee Jones wrote:

> > Some description blocks are void of any description/documentation,

> > others are missing 'struct' identifiers, there are also a couple of

> > misspellings of function parameter names.  Fix all of them.

> >

> > Fixes the following W=1 kernel build warning(s):

> >

> >  drivers/pinctrl/pinctrl-rza1.c:81: warning: cannot understand function prototype: 'struct rza1_bidir_pin '

> >  drivers/pinctrl/pinctrl-rza1.c:90: warning: cannot understand function prototype: 'struct rza1_bidir_entry '

> >  drivers/pinctrl/pinctrl-rza1.c:98: warning: cannot understand function prototype: 'struct rza1_swio_pin '

> >  drivers/pinctrl/pinctrl-rza1.c:108: warning: cannot understand function prototype: 'struct rza1_swio_entry '

> >  drivers/pinctrl/pinctrl-rza1.c:116: warning: cannot understand function prototype: 'struct rza1_pinmux_conf '

> >  drivers/pinctrl/pinctrl-rza1.c:443: warning: cannot understand function prototype: 'struct rza1_mux_conf '

> >  drivers/pinctrl/pinctrl-rza1.c:462: warning: cannot understand function prototype: 'struct rza1_port '

> >  drivers/pinctrl/pinctrl-rza1.c:482: warning: cannot understand function prototype: 'struct rza1_pinctrl '

> >  drivers/pinctrl/pinctrl-rza1.c:546: warning: Function parameter or member 'port' not described in 'rza1_pinmux_get_flags'

> >  drivers/pinctrl/pinctrl-rza1.c:546: warning: Function parameter or member 'pin' not described in 'rza1_pinmux_get_flags'

> >  drivers/pinctrl/pinctrl-rza1.c:546: warning: Function parameter or member 'func' not described in 'rza1_pinmux_get_flags'

> >  drivers/pinctrl/pinctrl-rza1.c:546: warning: Function parameter or member 'rza1_pctl' not described in 'rza1_pinmux_get_flags'

> >  drivers/pinctrl/pinctrl-rza1.c:575: warning: Function parameter or member 'port' not described in 'rza1_set_bit'

> >  drivers/pinctrl/pinctrl-rza1.c:575: warning: Function parameter or member 'reg' not described in 'rza1_set_bit'

> >  drivers/pinctrl/pinctrl-rza1.c:575: warning: Function parameter or member 'bit' not described in 'rza1_set_bit'

> >  drivers/pinctrl/pinctrl-rza1.c:575: warning: Function parameter or member 'set' not described in 'rza1_set_bit'

> >  drivers/pinctrl/pinctrl-rza1.c:672: warning: Function parameter or member 'rza1_pctl' not described in 'rza1_pin_mux_single'

> >  drivers/pinctrl/pinctrl-rza1.c:672: warning: Excess function parameter 'pinctrl' description in 'rza1_pin_mux_single'

> >

> > Cc: Geert Uytterhoeven <geert+renesas@glider.be>

> > Cc: Jacopo Mondi <jacopo+renesas@jmondi.org>

> > Cc: linux-renesas-soc@vger.kernel.org

> > Signed-off-by: Lee Jones <lee.jones@linaro.org>

> 

> Thanks, at the time I had no real idea about the implications of

> documenting with kerneldoc :)


You and 1000 others! :D

Don't lose any sleep over it.

> Acked-by: Jacopo Mondi <jacopo@jmondi.org>


Thanks.

-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog
Geert Uytterhoeven July 15, 2020, 7:30 a.m. | #3
Hi Lee,

On Mon, Jul 13, 2020 at 4:49 PM Lee Jones <lee.jones@linaro.org> wrote:
> Some description blocks are void of any description/documentation,

> others are missing 'struct' identifiers, there are also a couple of

> misspellings of function parameter names.  Fix all of them.

>

> Fixes the following W=1 kernel build warning(s):

>

>  drivers/pinctrl/pinctrl-rza1.c:81: warning: cannot understand function prototype: 'struct rza1_bidir_pin '

>  drivers/pinctrl/pinctrl-rza1.c:90: warning: cannot understand function prototype: 'struct rza1_bidir_entry '

>  drivers/pinctrl/pinctrl-rza1.c:98: warning: cannot understand function prototype: 'struct rza1_swio_pin '

>  drivers/pinctrl/pinctrl-rza1.c:108: warning: cannot understand function prototype: 'struct rza1_swio_entry '

>  drivers/pinctrl/pinctrl-rza1.c:116: warning: cannot understand function prototype: 'struct rza1_pinmux_conf '

>  drivers/pinctrl/pinctrl-rza1.c:443: warning: cannot understand function prototype: 'struct rza1_mux_conf '

>  drivers/pinctrl/pinctrl-rza1.c:462: warning: cannot understand function prototype: 'struct rza1_port '

>  drivers/pinctrl/pinctrl-rza1.c:482: warning: cannot understand function prototype: 'struct rza1_pinctrl '

>  drivers/pinctrl/pinctrl-rza1.c:546: warning: Function parameter or member 'port' not described in 'rza1_pinmux_get_flags'

>  drivers/pinctrl/pinctrl-rza1.c:546: warning: Function parameter or member 'pin' not described in 'rza1_pinmux_get_flags'

>  drivers/pinctrl/pinctrl-rza1.c:546: warning: Function parameter or member 'func' not described in 'rza1_pinmux_get_flags'

>  drivers/pinctrl/pinctrl-rza1.c:546: warning: Function parameter or member 'rza1_pctl' not described in 'rza1_pinmux_get_flags'

>  drivers/pinctrl/pinctrl-rza1.c:575: warning: Function parameter or member 'port' not described in 'rza1_set_bit'

>  drivers/pinctrl/pinctrl-rza1.c:575: warning: Function parameter or member 'reg' not described in 'rza1_set_bit'

>  drivers/pinctrl/pinctrl-rza1.c:575: warning: Function parameter or member 'bit' not described in 'rza1_set_bit'

>  drivers/pinctrl/pinctrl-rza1.c:575: warning: Function parameter or member 'set' not described in 'rza1_set_bit'

>  drivers/pinctrl/pinctrl-rza1.c:672: warning: Function parameter or member 'rza1_pctl' not described in 'rza1_pin_mux_single'

>  drivers/pinctrl/pinctrl-rza1.c:672: warning: Excess function parameter 'pinctrl' description in 'rza1_pin_mux_single'

>

> Cc: Geert Uytterhoeven <geert+renesas@glider.be>

> Cc: Jacopo Mondi <jacopo+renesas@jmondi.org>

> Cc: linux-renesas-soc@vger.kernel.org

> Signed-off-by: Lee Jones <lee.jones@linaro.org>


Reviewed-by: Geert Uytterhoeven <geert+renesas@glider.be>

i.e. will queue in sh-pfc-for-v5.9.

Gr{oetje,eeting}s,

                        Geert

-- 
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds
Linus Walleij July 16, 2020, 1:57 p.m. | #4
On Wed, Jul 15, 2020 at 9:30 AM Geert Uytterhoeven <geert@linux-m68k.org> wrote:

> Reviewed-by: Geert Uytterhoeven <geert+renesas@glider.be>

> i.e. will queue in sh-pfc-for-v5.9.


OK since Geert is queueing this I'll drop this patch from my tree.

Yours,
Linus Walleij
Geert Uytterhoeven July 16, 2020, 2:12 p.m. | #5
Hi Linus,

On Thu, Jul 16, 2020 at 3:57 PM Linus Walleij <linus.walleij@linaro.org> wrote:
> On Wed, Jul 15, 2020 at 9:30 AM Geert Uytterhoeven <geert@linux-m68k.org> wrote:

> > Reviewed-by: Geert Uytterhoeven <geert+renesas@glider.be>

> > i.e. will queue in sh-pfc-for-v5.9.

>

> OK since Geert is queueing this I'll drop this patch from my tree.


Oops, sorry, I didn't know you were planning to apply this one.

Gr{oetje,eeting}s,

                        Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds

Patch

diff --git a/drivers/pinctrl/pinctrl-rza1.c b/drivers/pinctrl/pinctrl-rza1.c
index 38a14bbced5f6..511f232ab7bc2 100644
--- a/drivers/pinctrl/pinctrl-rza1.c
+++ b/drivers/pinctrl/pinctrl-rza1.c
@@ -75,7 +75,7 @@ 
  * RZ/A1 pinmux flags
  */
 
-/**
+/*
  * rza1_bidir_pin - describe a single pin that needs bidir flag applied.
  */
 struct rza1_bidir_pin {
@@ -83,7 +83,7 @@  struct rza1_bidir_pin {
 	u8 func: 4;
 };
 
-/**
+/*
  * rza1_bidir_entry - describe a list of pins that needs bidir flag applied.
  *		      Each struct rza1_bidir_entry describes a port.
  */
@@ -92,7 +92,7 @@  struct rza1_bidir_entry {
 	const struct rza1_bidir_pin *pins;
 };
 
-/**
+/*
  * rza1_swio_pin - describe a single pin that needs swio flag applied.
  */
 struct rza1_swio_pin {
@@ -102,7 +102,7 @@  struct rza1_swio_pin {
 	u16 input: 1;
 };
 
-/**
+/*
  * rza1_swio_entry - describe a list of pins that needs swio flag applied
  */
 struct rza1_swio_entry {
@@ -110,7 +110,7 @@  struct rza1_swio_entry {
 	const struct rza1_swio_pin *pins;
 };
 
-/**
+/*
  * rza1_pinmux_conf - group together bidir and swio pinmux flag tables
  */
 struct rza1_pinmux_conf {
@@ -431,7 +431,7 @@  static const struct rza1_pinmux_conf rza1l_pmx_conf = {
  * RZ/A1 types
  */
 /**
- * rza1_mux_conf - describes a pin multiplexing operation
+ * struct rza1_mux_conf - describes a pin multiplexing operation
  *
  * @id: the pin identifier from 0 to RZA1_NPINS
  * @port: the port where pin sits on
@@ -450,7 +450,7 @@  struct rza1_mux_conf {
 };
 
 /**
- * rza1_port - describes a pin port
+ * struct rza1_port - describes a pin port
  *
  * This is mostly useful to lock register writes per-bank and not globally.
  *
@@ -467,12 +467,12 @@  struct rza1_port {
 };
 
 /**
- * rza1_pinctrl - RZ pincontroller device
+ * struct rza1_pinctrl - RZ pincontroller device
  *
  * @dev: parent device structure
  * @mutex: protect [pinctrl|pinmux]_generic functions
  * @base: logical address base
- * @nports: number of pin controller ports
+ * @nport: number of pin controller ports
  * @ports: pin controller banks
  * @pins: pin array for pinctrl core
  * @desc: pincontroller desc for pinctrl core
@@ -536,7 +536,7 @@  static inline int rza1_pinmux_get_swio(unsigned int port,
 	return -ENOENT;
 }
 
-/**
+/*
  * rza1_pinmux_get_flags() - return pinmux flags associated to a pin
  */
 static unsigned int rza1_pinmux_get_flags(unsigned int port, unsigned int pin,
@@ -566,7 +566,7 @@  static unsigned int rza1_pinmux_get_flags(unsigned int port, unsigned int pin,
  * RZ/A1 SoC operations
  */
 
-/**
+/*
  * rza1_set_bit() - un-locked set/clear a single bit in pin configuration
  *		    registers
  */
@@ -664,7 +664,7 @@  static inline int rza1_pin_get(struct rza1_port *port, unsigned int pin)
 /**
  * rza1_pin_mux_single() - configure pin multiplexing on a single pin
  *
- * @pinctrl: RZ/A1 pin controller device
+ * @rza1_pctl: RZ/A1 pin controller device
  * @mux_conf: pin multiplexing descriptor
  */
 static int rza1_pin_mux_single(struct rza1_pinctrl *rza1_pctl,