All of lore.kernel.org
 help / color / mirror / Atom feed
* [PATCH] clk/at91: remove kernel-doc warnings in sama7g5.c
@ 2021-08-10  0:54 ` Randy Dunlap
  0 siblings, 0 replies; 8+ messages in thread
From: Randy Dunlap @ 2021-08-10  0:54 UTC (permalink / raw)
  To: linux-kernel
  Cc: Randy Dunlap, kernel test robot, Claudiu Beznea,
	Michael Turquette, Stephen Boyd, Eugen Hristev, linux-clk,
	linux-doc, linux-arm-kernel, Jonathan Corbet

Fix multiple kernel-doc warnings in sama7g5.c. There are several
enums and structs that were not identified as such.
There are also several anonymous structs (that scripts/kernel-doc
has problems with), so add struct names to them.

Fixes the following warnings:

drivers/clk/at91/sama7g5.c:39: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * PLL clocks identifiers
drivers/clk/at91/sama7g5.c:60: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * PLL type identifiers
drivers/clk/at91/sama7g5.c:122: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * PLL clocks description
drivers/clk/at91/sama7g5.c:289: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * Master clock (MCK[1..4]) description
drivers/clk/at91/sama7g5.c:341: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * System clock description
drivers/clk/at91/sama7g5.c:365: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * Peripheral clock description
drivers/clk/at91/sama7g5.c:453: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * Generic clock description
drivers/clk/at91/sama7g5.c:339: warning: Function parameter or member 'ep_chg_id' not described in 'master_clock'

Some kernel-doc warnings are still printed, but they are all due to
problems in the kernel-doc script (if anyone is interested in playing
with some Perl :). These warnings are:

sama7g5.c:287: warning: Function parameter or member '{' not described in 'sama7g5_plls'
sama7g5.c:287: warning: Function parameter or member '' not described in 'sama7g5_plls'
sama7g5.c:287: warning: Function parameter or member '}' not described in 'sama7g5_plls'
sama7g5.c:339: warning: Function parameter or member 'sama7g5_mckx' not described in 'master_clock'
sama7g5.c:339: warning: Function parameter or member '}' not described in 'master_clock'
sama7g5.c:360: warning: Function parameter or member 'sama7g5_systemck' not described in 'system_clock'
sama7g5.c:451: warning: Function parameter or member 'sama7g5_periphck' not described in 'periph_clock'
sama7g5.c:451: warning: Function parameter or member '' not described in 'periph_clock'
sama7g5.c:451: warning: Function parameter or member '}' not described in 'periph_clock'
sama7g5.c:841: warning: Function parameter or member 'sama7g5_gck' not described in 'generic_clock'
sama7g5.c:841: warning: Function parameter or member '}' not described in 'generic_clock'

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Reported-by: kernel test robot <lkp@intel.com>
Cc: Claudiu Beznea <claudiu.beznea@microchip.com>
Cc: Michael Turquette <mturquette@baylibre.com>
Cc: Stephen Boyd <sboyd@kernel.org>
Cc: Eugen Hristev <eugen.hristev@microchip.com>
Cc: linux-clk@vger.kernel.org
Cc: linux-doc@vger.kernel.org
Cc: linux-arm-kernel@lists.infradead.org
Cc: Jonathan Corbet <corbet@lwn.net>
---
 drivers/clk/at91/sama7g5.c |   27 ++++++++++++++-------------
 1 file changed, 14 insertions(+), 13 deletions(-)

--- linux-next-20210809.orig/drivers/clk/at91/sama7g5.c
+++ linux-next-20210809/drivers/clk/at91/sama7g5.c
@@ -36,7 +36,7 @@ static DEFINE_SPINLOCK(pmc_mck0_lock);
 static DEFINE_SPINLOCK(pmc_mckX_lock);
 
 /**
- * PLL clocks identifiers
+ * enum pll_ids - PLL clocks identifiers
  * @PLL_ID_CPU:		CPU PLL identifier
  * @PLL_ID_SYS:		System PLL identifier
  * @PLL_ID_DDR:		DDR PLL identifier
@@ -44,6 +44,7 @@ static DEFINE_SPINLOCK(pmc_mckX_lock);
  * @PLL_ID_BAUD:	Baud PLL identifier
  * @PLL_ID_AUDIO:	Audio PLL identifier
  * @PLL_ID_ETH:		Ethernet PLL identifier
+ * @PLL_ID_MAX:		Number of PLL_ID values (1 more than the last valid PLL_ID)
  */
 enum pll_ids {
 	PLL_ID_CPU,
@@ -57,7 +58,7 @@ enum pll_ids {
 };
 
 /**
- * PLL type identifiers
+ * enum pll_type - PLL type identifiers
  * @PLL_TYPE_FRAC:	fractional PLL identifier
  * @PLL_TYPE_DIV:	divider PLL identifier
  */
@@ -119,7 +120,7 @@ static const struct clk_pll_characterist
 };
 
 /**
- * PLL clocks description
+ * struct sama7g5_plls - PLL clocks description
  * @n:		clock name
  * @p:		clock parent
  * @l:		clock layout
@@ -128,7 +129,7 @@ static const struct clk_pll_characterist
  * @f:		clock flags
  * @eid:	export index in sama7g5->chws[] array
  */
-static const struct {
+static const struct sama7g5_plls {
 	const char *n;
 	const char *p;
 	const struct clk_pll_layout *l;
@@ -286,17 +287,17 @@ static const struct {
 };
 
 /**
- * Master clock (MCK[1..4]) description
+ * struct master_clock - Master clock (MCK[1..4]) description
  * @n:			clock name
  * @ep:			extra parents names array
- * @ep_chg_chg_id:	index in parents array that specifies the changeable
+ * @ep_chg_id:		index in parents array that specifies the changeable
  *			parent
  * @ep_count:		extra parents count
  * @ep_mux_table:	mux table for extra parents
  * @id:			clock id
  * @c:			true if clock is critical and cannot be disabled
  */
-static const struct {
+static const struct master_clock {
 	const char *n;
 	const char *ep[4];
 	int ep_chg_id;
@@ -338,12 +339,12 @@ static const struct {
 };
 
 /**
- * System clock description
+ * struct system_clock - System clock description
  * @n:	clock name
  * @p:	clock parent name
  * @id: clock id
  */
-static const struct {
+static const struct system_clock {
 	const char *n;
 	const char *p;
 	u8 id;
@@ -362,14 +363,14 @@ static const struct {
 static u32 sama7g5_prog_mux_table[] = { 0, 1, 2, 5, 6, 7, 8, 9, 10, };
 
 /**
- * Peripheral clock description
+ * struct periph_clock - Peripheral clock description
  * @n:		clock name
  * @p:		clock parent name
  * @r:		clock range values
  * @id:		clock id
  * @chgp:	index in parent array of the changeable parent
  */
-static const struct {
+static const struct periph_clock {
 	const char *n;
 	const char *p;
 	struct clk_range r;
@@ -450,7 +451,7 @@ static const struct {
 };
 
 /**
- * Generic clock description
+ * struct generic_clock - Generic clock description
  * @n:			clock name
  * @pp:			PLL parents
  * @pp_mux_table:	PLL parents mux table
@@ -459,7 +460,7 @@ static const struct {
  * @pp_count:		PLL parents count
  * @id:			clock id
  */
-static const struct {
+static const struct generic_clock {
 	const char *n;
 	const char *pp[8];
 	const char pp_mux_table[8];

^ permalink raw reply	[flat|nested] 8+ messages in thread
* [PATCH] clk/at91: remove kernel-doc warnings in sama7g5.c
@ 2021-08-10  0:54 ` Randy Dunlap
  0 siblings, 0 replies; 8+ messages in thread
From: Randy Dunlap @ 2021-08-10  0:54 UTC (permalink / raw)
  To: linux-kernel
  Cc: Randy Dunlap, kernel test robot, Claudiu Beznea,
	Michael Turquette, Stephen Boyd, Eugen Hristev, linux-clk,
	linux-doc, linux-arm-kernel, Jonathan Corbet

Fix multiple kernel-doc warnings in sama7g5.c. There are several
enums and structs that were not identified as such.
There are also several anonymous structs (that scripts/kernel-doc
has problems with), so add struct names to them.

Fixes the following warnings:

drivers/clk/at91/sama7g5.c:39: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * PLL clocks identifiers
drivers/clk/at91/sama7g5.c:60: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * PLL type identifiers
drivers/clk/at91/sama7g5.c:122: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * PLL clocks description
drivers/clk/at91/sama7g5.c:289: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * Master clock (MCK[1..4]) description
drivers/clk/at91/sama7g5.c:341: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * System clock description
drivers/clk/at91/sama7g5.c:365: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * Peripheral clock description
drivers/clk/at91/sama7g5.c:453: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * Generic clock description
drivers/clk/at91/sama7g5.c:339: warning: Function parameter or member 'ep_chg_id' not described in 'master_clock'

Some kernel-doc warnings are still printed, but they are all due to
problems in the kernel-doc script (if anyone is interested in playing
with some Perl :). These warnings are:

sama7g5.c:287: warning: Function parameter or member '{' not described in 'sama7g5_plls'
sama7g5.c:287: warning: Function parameter or member '' not described in 'sama7g5_plls'
sama7g5.c:287: warning: Function parameter or member '}' not described in 'sama7g5_plls'
sama7g5.c:339: warning: Function parameter or member 'sama7g5_mckx' not described in 'master_clock'
sama7g5.c:339: warning: Function parameter or member '}' not described in 'master_clock'
sama7g5.c:360: warning: Function parameter or member 'sama7g5_systemck' not described in 'system_clock'
sama7g5.c:451: warning: Function parameter or member 'sama7g5_periphck' not described in 'periph_clock'
sama7g5.c:451: warning: Function parameter or member '' not described in 'periph_clock'
sama7g5.c:451: warning: Function parameter or member '}' not described in 'periph_clock'
sama7g5.c:841: warning: Function parameter or member 'sama7g5_gck' not described in 'generic_clock'
sama7g5.c:841: warning: Function parameter or member '}' not described in 'generic_clock'

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Reported-by: kernel test robot <lkp@intel.com>
Cc: Claudiu Beznea <claudiu.beznea@microchip.com>
Cc: Michael Turquette <mturquette@baylibre.com>
Cc: Stephen Boyd <sboyd@kernel.org>
Cc: Eugen Hristev <eugen.hristev@microchip.com>
Cc: linux-clk@vger.kernel.org
Cc: linux-doc@vger.kernel.org
Cc: linux-arm-kernel@lists.infradead.org
Cc: Jonathan Corbet <corbet@lwn.net>
---
 drivers/clk/at91/sama7g5.c |   27 ++++++++++++++-------------
 1 file changed, 14 insertions(+), 13 deletions(-)

--- linux-next-20210809.orig/drivers/clk/at91/sama7g5.c
+++ linux-next-20210809/drivers/clk/at91/sama7g5.c
@@ -36,7 +36,7 @@ static DEFINE_SPINLOCK(pmc_mck0_lock);
 static DEFINE_SPINLOCK(pmc_mckX_lock);
 
 /**
- * PLL clocks identifiers
+ * enum pll_ids - PLL clocks identifiers
  * @PLL_ID_CPU:		CPU PLL identifier
  * @PLL_ID_SYS:		System PLL identifier
  * @PLL_ID_DDR:		DDR PLL identifier
@@ -44,6 +44,7 @@ static DEFINE_SPINLOCK(pmc_mckX_lock);
  * @PLL_ID_BAUD:	Baud PLL identifier
  * @PLL_ID_AUDIO:	Audio PLL identifier
  * @PLL_ID_ETH:		Ethernet PLL identifier
+ * @PLL_ID_MAX:		Number of PLL_ID values (1 more than the last valid PLL_ID)
  */
 enum pll_ids {
 	PLL_ID_CPU,
@@ -57,7 +58,7 @@ enum pll_ids {
 };
 
 /**
- * PLL type identifiers
+ * enum pll_type - PLL type identifiers
  * @PLL_TYPE_FRAC:	fractional PLL identifier
  * @PLL_TYPE_DIV:	divider PLL identifier
  */
@@ -119,7 +120,7 @@ static const struct clk_pll_characterist
 };
 
 /**
- * PLL clocks description
+ * struct sama7g5_plls - PLL clocks description
  * @n:		clock name
  * @p:		clock parent
  * @l:		clock layout
@@ -128,7 +129,7 @@ static const struct clk_pll_characterist
  * @f:		clock flags
  * @eid:	export index in sama7g5->chws[] array
  */
-static const struct {
+static const struct sama7g5_plls {
 	const char *n;
 	const char *p;
 	const struct clk_pll_layout *l;
@@ -286,17 +287,17 @@ static const struct {
 };
 
 /**
- * Master clock (MCK[1..4]) description
+ * struct master_clock - Master clock (MCK[1..4]) description
  * @n:			clock name
  * @ep:			extra parents names array
- * @ep_chg_chg_id:	index in parents array that specifies the changeable
+ * @ep_chg_id:		index in parents array that specifies the changeable
  *			parent
  * @ep_count:		extra parents count
  * @ep_mux_table:	mux table for extra parents
  * @id:			clock id
  * @c:			true if clock is critical and cannot be disabled
  */
-static const struct {
+static const struct master_clock {
 	const char *n;
 	const char *ep[4];
 	int ep_chg_id;
@@ -338,12 +339,12 @@ static const struct {
 };
 
 /**
- * System clock description
+ * struct system_clock - System clock description
  * @n:	clock name
  * @p:	clock parent name
  * @id: clock id
  */
-static const struct {
+static const struct system_clock {
 	const char *n;
 	const char *p;
 	u8 id;
@@ -362,14 +363,14 @@ static const struct {
 static u32 sama7g5_prog_mux_table[] = { 0, 1, 2, 5, 6, 7, 8, 9, 10, };
 
 /**
- * Peripheral clock description
+ * struct periph_clock - Peripheral clock description
  * @n:		clock name
  * @p:		clock parent name
  * @r:		clock range values
  * @id:		clock id
  * @chgp:	index in parent array of the changeable parent
  */
-static const struct {
+static const struct periph_clock {
 	const char *n;
 	const char *p;
 	struct clk_range r;
@@ -450,7 +451,7 @@ static const struct {
 };
 
 /**
- * Generic clock description
+ * struct generic_clock - Generic clock description
  * @n:			clock name
  * @pp:			PLL parents
  * @pp_mux_table:	PLL parents mux table
@@ -459,7 +460,7 @@ static const struct {
  * @pp_count:		PLL parents count
  * @id:			clock id
  */
-static const struct {
+static const struct generic_clock {
 	const char *n;
 	const char *pp[8];
 	const char pp_mux_table[8];

_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

^ permalink raw reply	[flat|nested] 8+ messages in thread
* Re: [PATCH] clk/at91: remove kernel-doc warnings in sama7g5.c
  2021-08-10  0:54 ` Randy Dunlap
@ 2021-08-18  5:12   ` Claudiu.Beznea
  -1 siblings, 0 replies; 8+ messages in thread
From: Claudiu.Beznea @ 2021-08-18  5:12 UTC (permalink / raw)
  To: rdunlap, linux-kernel
  Cc: lkp, mturquette, sboyd, Eugen.Hristev, linux-clk, linux-doc,
	linux-arm-kernel, corbet

Hi Randy,

On 10.08.2021 03:54, Randy Dunlap wrote:
> EXTERNAL EMAIL: Do not click links or open attachments unless you know the content is safe
> 
> Fix multiple kernel-doc warnings in sama7g5.c. There are several
> enums and structs that were not identified as such.
> There are also several anonymous structs (that scripts/kernel-doc
> has problems with), so add struct names to them.
> 
> Fixes the following warnings:
> 
> drivers/clk/at91/sama7g5.c:39: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>  * PLL clocks identifiers
> drivers/clk/at91/sama7g5.c:60: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>  * PLL type identifiers
> drivers/clk/at91/sama7g5.c:122: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>  * PLL clocks description
> drivers/clk/at91/sama7g5.c:289: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>  * Master clock (MCK[1..4]) description
> drivers/clk/at91/sama7g5.c:341: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>  * System clock description
> drivers/clk/at91/sama7g5.c:365: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>  * Peripheral clock description
> drivers/clk/at91/sama7g5.c:453: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>  * Generic clock description
> drivers/clk/at91/sama7g5.c:339: warning: Function parameter or member 'ep_chg_id' not described in 'master_clock'
> 
> Some kernel-doc warnings are still printed, but they are all due to
> problems in the kernel-doc script (if anyone is interested in playing
> with some Perl :). These warnings are:
> 
> sama7g5.c:287: warning: Function parameter or member '{' not described in 'sama7g5_plls'
> sama7g5.c:287: warning: Function parameter or member '' not described in 'sama7g5_plls'
> sama7g5.c:287: warning: Function parameter or member '}' not described in 'sama7g5_plls'
> sama7g5.c:339: warning: Function parameter or member 'sama7g5_mckx' not described in 'master_clock'
> sama7g5.c:339: warning: Function parameter or member '}' not described in 'master_clock'
> sama7g5.c:360: warning: Function parameter or member 'sama7g5_systemck' not described in 'system_clock'
> sama7g5.c:451: warning: Function parameter or member 'sama7g5_periphck' not described in 'periph_clock'
> sama7g5.c:451: warning: Function parameter or member '' not described in 'periph_clock'
> sama7g5.c:451: warning: Function parameter or member '}' not described in 'periph_clock'
> sama7g5.c:841: warning: Function parameter or member 'sama7g5_gck' not described in 'generic_clock'
> sama7g5.c:841: warning: Function parameter or member '}' not described in 'generic_clock'

What about keeping only one '*' instead of '**' where necessary as these
data structures are only local to sama7g5.c file (according to
Documentation/doc-guide/kernel-doc.rst "Functions and data structures in
header files which are intended to be used by modules should also have
kernel-doc comments."). This way all the warnings will be gone.

Thank you,
Claudiu Beznea

> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Reported-by: kernel test robot <lkp@intel.com>
> Cc: Claudiu Beznea <claudiu.beznea@microchip.com>
> Cc: Michael Turquette <mturquette@baylibre.com>
> Cc: Stephen Boyd <sboyd@kernel.org>
> Cc: Eugen Hristev <eugen.hristev@microchip.com>
> Cc: linux-clk@vger.kernel.org
> Cc: linux-doc@vger.kernel.org
> Cc: linux-arm-kernel@lists.infradead.org
> Cc: Jonathan Corbet <corbet@lwn.net>
> ---
>  drivers/clk/at91/sama7g5.c |   27 ++++++++++++++-------------
>  1 file changed, 14 insertions(+), 13 deletions(-)
> 
> --- linux-next-20210809.orig/drivers/clk/at91/sama7g5.c
> +++ linux-next-20210809/drivers/clk/at91/sama7g5.c
> @@ -36,7 +36,7 @@ static DEFINE_SPINLOCK(pmc_mck0_lock);
>  static DEFINE_SPINLOCK(pmc_mckX_lock);
> 
>  /**
> - * PLL clocks identifiers
> + * enum pll_ids - PLL clocks identifiers
>   * @PLL_ID_CPU:                CPU PLL identifier
>   * @PLL_ID_SYS:                System PLL identifier
>   * @PLL_ID_DDR:                DDR PLL identifier
> @@ -44,6 +44,7 @@ static DEFINE_SPINLOCK(pmc_mckX_lock);
>   * @PLL_ID_BAUD:       Baud PLL identifier
>   * @PLL_ID_AUDIO:      Audio PLL identifier
>   * @PLL_ID_ETH:                Ethernet PLL identifier
> + * @PLL_ID_MAX:                Number of PLL_ID values (1 more than the last valid PLL_ID)
>   */
>  enum pll_ids {
>         PLL_ID_CPU,
> @@ -57,7 +58,7 @@ enum pll_ids {
>  };
> 
>  /**
> - * PLL type identifiers
> + * enum pll_type - PLL type identifiers
>   * @PLL_TYPE_FRAC:     fractional PLL identifier
>   * @PLL_TYPE_DIV:      divider PLL identifier
>   */
> @@ -119,7 +120,7 @@ static const struct clk_pll_characterist
>  };
> 
>  /**
> - * PLL clocks description
> + * struct sama7g5_plls - PLL clocks description
>   * @n:         clock name
>   * @p:         clock parent
>   * @l:         clock layout
> @@ -128,7 +129,7 @@ static const struct clk_pll_characterist
>   * @f:         clock flags
>   * @eid:       export index in sama7g5->chws[] array
>   */
> -static const struct {
> +static const struct sama7g5_plls {
>         const char *n;
>         const char *p;
>         const struct clk_pll_layout *l;
> @@ -286,17 +287,17 @@ static const struct {
>  };
> 
>  /**
> - * Master clock (MCK[1..4]) description
> + * struct master_clock - Master clock (MCK[1..4]) description
>   * @n:                 clock name
>   * @ep:                        extra parents names array
> - * @ep_chg_chg_id:     index in parents array that specifies the changeable
> + * @ep_chg_id:         index in parents array that specifies the changeable
>   *                     parent
>   * @ep_count:          extra parents count
>   * @ep_mux_table:      mux table for extra parents
>   * @id:                        clock id
>   * @c:                 true if clock is critical and cannot be disabled
>   */
> -static const struct {
> +static const struct master_clock {
>         const char *n;
>         const char *ep[4];
>         int ep_chg_id;
> @@ -338,12 +339,12 @@ static const struct {
>  };
> 
>  /**
> - * System clock description
> + * struct system_clock - System clock description
>   * @n: clock name
>   * @p: clock parent name
>   * @id: clock id
>   */
> -static const struct {
> +static const struct system_clock {
>         const char *n;
>         const char *p;
>         u8 id;
> @@ -362,14 +363,14 @@ static const struct {
>  static u32 sama7g5_prog_mux_table[] = { 0, 1, 2, 5, 6, 7, 8, 9, 10, };
> 
>  /**
> - * Peripheral clock description
> + * struct periph_clock - Peripheral clock description
>   * @n:         clock name
>   * @p:         clock parent name
>   * @r:         clock range values
>   * @id:                clock id
>   * @chgp:      index in parent array of the changeable parent
>   */
> -static const struct {
> +static const struct periph_clock {
>         const char *n;
>         const char *p;
>         struct clk_range r;
> @@ -450,7 +451,7 @@ static const struct {
>  };
> 
>  /**
> - * Generic clock description
> + * struct generic_clock - Generic clock description
>   * @n:                 clock name
>   * @pp:                        PLL parents
>   * @pp_mux_table:      PLL parents mux table
> @@ -459,7 +460,7 @@ static const struct {
>   * @pp_count:          PLL parents count
>   * @id:                        clock id
>   */
> -static const struct {
> +static const struct generic_clock {
>         const char *n;
>         const char *pp[8];
>         const char pp_mux_table[8];
> 


^ permalink raw reply	[flat|nested] 8+ messages in thread
* Re: [PATCH] clk/at91: remove kernel-doc warnings in sama7g5.c
@ 2021-08-18  5:12   ` Claudiu.Beznea
  0 siblings, 0 replies; 8+ messages in thread
From: Claudiu.Beznea @ 2021-08-18  5:12 UTC (permalink / raw)
  To: rdunlap, linux-kernel
  Cc: lkp, mturquette, sboyd, Eugen.Hristev, linux-clk, linux-doc,
	linux-arm-kernel, corbet

Hi Randy,

On 10.08.2021 03:54, Randy Dunlap wrote:
> EXTERNAL EMAIL: Do not click links or open attachments unless you know the content is safe
> 
> Fix multiple kernel-doc warnings in sama7g5.c. There are several
> enums and structs that were not identified as such.
> There are also several anonymous structs (that scripts/kernel-doc
> has problems with), so add struct names to them.
> 
> Fixes the following warnings:
> 
> drivers/clk/at91/sama7g5.c:39: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>  * PLL clocks identifiers
> drivers/clk/at91/sama7g5.c:60: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>  * PLL type identifiers
> drivers/clk/at91/sama7g5.c:122: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>  * PLL clocks description
> drivers/clk/at91/sama7g5.c:289: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>  * Master clock (MCK[1..4]) description
> drivers/clk/at91/sama7g5.c:341: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>  * System clock description
> drivers/clk/at91/sama7g5.c:365: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>  * Peripheral clock description
> drivers/clk/at91/sama7g5.c:453: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>  * Generic clock description
> drivers/clk/at91/sama7g5.c:339: warning: Function parameter or member 'ep_chg_id' not described in 'master_clock'
> 
> Some kernel-doc warnings are still printed, but they are all due to
> problems in the kernel-doc script (if anyone is interested in playing
> with some Perl :). These warnings are:
> 
> sama7g5.c:287: warning: Function parameter or member '{' not described in 'sama7g5_plls'
> sama7g5.c:287: warning: Function parameter or member '' not described in 'sama7g5_plls'
> sama7g5.c:287: warning: Function parameter or member '}' not described in 'sama7g5_plls'
> sama7g5.c:339: warning: Function parameter or member 'sama7g5_mckx' not described in 'master_clock'
> sama7g5.c:339: warning: Function parameter or member '}' not described in 'master_clock'
> sama7g5.c:360: warning: Function parameter or member 'sama7g5_systemck' not described in 'system_clock'
> sama7g5.c:451: warning: Function parameter or member 'sama7g5_periphck' not described in 'periph_clock'
> sama7g5.c:451: warning: Function parameter or member '' not described in 'periph_clock'
> sama7g5.c:451: warning: Function parameter or member '}' not described in 'periph_clock'
> sama7g5.c:841: warning: Function parameter or member 'sama7g5_gck' not described in 'generic_clock'
> sama7g5.c:841: warning: Function parameter or member '}' not described in 'generic_clock'

What about keeping only one '*' instead of '**' where necessary as these
data structures are only local to sama7g5.c file (according to
Documentation/doc-guide/kernel-doc.rst "Functions and data structures in
header files which are intended to be used by modules should also have
kernel-doc comments."). This way all the warnings will be gone.

Thank you,
Claudiu Beznea

> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Reported-by: kernel test robot <lkp@intel.com>
> Cc: Claudiu Beznea <claudiu.beznea@microchip.com>
> Cc: Michael Turquette <mturquette@baylibre.com>
> Cc: Stephen Boyd <sboyd@kernel.org>
> Cc: Eugen Hristev <eugen.hristev@microchip.com>
> Cc: linux-clk@vger.kernel.org
> Cc: linux-doc@vger.kernel.org
> Cc: linux-arm-kernel@lists.infradead.org
> Cc: Jonathan Corbet <corbet@lwn.net>
> ---
>  drivers/clk/at91/sama7g5.c |   27 ++++++++++++++-------------
>  1 file changed, 14 insertions(+), 13 deletions(-)
> 
> --- linux-next-20210809.orig/drivers/clk/at91/sama7g5.c
> +++ linux-next-20210809/drivers/clk/at91/sama7g5.c
> @@ -36,7 +36,7 @@ static DEFINE_SPINLOCK(pmc_mck0_lock);
>  static DEFINE_SPINLOCK(pmc_mckX_lock);
> 
>  /**
> - * PLL clocks identifiers
> + * enum pll_ids - PLL clocks identifiers
>   * @PLL_ID_CPU:                CPU PLL identifier
>   * @PLL_ID_SYS:                System PLL identifier
>   * @PLL_ID_DDR:                DDR PLL identifier
> @@ -44,6 +44,7 @@ static DEFINE_SPINLOCK(pmc_mckX_lock);
>   * @PLL_ID_BAUD:       Baud PLL identifier
>   * @PLL_ID_AUDIO:      Audio PLL identifier
>   * @PLL_ID_ETH:                Ethernet PLL identifier
> + * @PLL_ID_MAX:                Number of PLL_ID values (1 more than the last valid PLL_ID)
>   */
>  enum pll_ids {
>         PLL_ID_CPU,
> @@ -57,7 +58,7 @@ enum pll_ids {
>  };
> 
>  /**
> - * PLL type identifiers
> + * enum pll_type - PLL type identifiers
>   * @PLL_TYPE_FRAC:     fractional PLL identifier
>   * @PLL_TYPE_DIV:      divider PLL identifier
>   */
> @@ -119,7 +120,7 @@ static const struct clk_pll_characterist
>  };
> 
>  /**
> - * PLL clocks description
> + * struct sama7g5_plls - PLL clocks description
>   * @n:         clock name
>   * @p:         clock parent
>   * @l:         clock layout
> @@ -128,7 +129,7 @@ static const struct clk_pll_characterist
>   * @f:         clock flags
>   * @eid:       export index in sama7g5->chws[] array
>   */
> -static const struct {
> +static const struct sama7g5_plls {
>         const char *n;
>         const char *p;
>         const struct clk_pll_layout *l;
> @@ -286,17 +287,17 @@ static const struct {
>  };
> 
>  /**
> - * Master clock (MCK[1..4]) description
> + * struct master_clock - Master clock (MCK[1..4]) description
>   * @n:                 clock name
>   * @ep:                        extra parents names array
> - * @ep_chg_chg_id:     index in parents array that specifies the changeable
> + * @ep_chg_id:         index in parents array that specifies the changeable
>   *                     parent
>   * @ep_count:          extra parents count
>   * @ep_mux_table:      mux table for extra parents
>   * @id:                        clock id
>   * @c:                 true if clock is critical and cannot be disabled
>   */
> -static const struct {
> +static const struct master_clock {
>         const char *n;
>         const char *ep[4];
>         int ep_chg_id;
> @@ -338,12 +339,12 @@ static const struct {
>  };
> 
>  /**
> - * System clock description
> + * struct system_clock - System clock description
>   * @n: clock name
>   * @p: clock parent name
>   * @id: clock id
>   */
> -static const struct {
> +static const struct system_clock {
>         const char *n;
>         const char *p;
>         u8 id;
> @@ -362,14 +363,14 @@ static const struct {
>  static u32 sama7g5_prog_mux_table[] = { 0, 1, 2, 5, 6, 7, 8, 9, 10, };
> 
>  /**
> - * Peripheral clock description
> + * struct periph_clock - Peripheral clock description
>   * @n:         clock name
>   * @p:         clock parent name
>   * @r:         clock range values
>   * @id:                clock id
>   * @chgp:      index in parent array of the changeable parent
>   */
> -static const struct {
> +static const struct periph_clock {
>         const char *n;
>         const char *p;
>         struct clk_range r;
> @@ -450,7 +451,7 @@ static const struct {
>  };
> 
>  /**
> - * Generic clock description
> + * struct generic_clock - Generic clock description
>   * @n:                 clock name
>   * @pp:                        PLL parents
>   * @pp_mux_table:      PLL parents mux table
> @@ -459,7 +460,7 @@ static const struct {
>   * @pp_count:          PLL parents count
>   * @id:                        clock id
>   */
> -static const struct {
> +static const struct generic_clock {
>         const char *n;
>         const char *pp[8];
>         const char pp_mux_table[8];
> 

_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

^ permalink raw reply	[flat|nested] 8+ messages in thread
* Re: [PATCH] clk/at91: remove kernel-doc warnings in sama7g5.c
  2021-08-18  5:12   ` Claudiu.Beznea
@ 2021-08-18  5:32     ` Randy Dunlap
  -1 siblings, 0 replies; 8+ messages in thread
From: Randy Dunlap @ 2021-08-18  5:32 UTC (permalink / raw)
  To: Claudiu.Beznea, linux-kernel
  Cc: lkp, mturquette, sboyd, Eugen.Hristev, linux-clk, linux-doc,
	linux-arm-kernel, corbet

On 8/17/21 10:12 PM, Claudiu.Beznea@microchip.com wrote:
> Hi Randy,
> 
> On 10.08.2021 03:54, Randy Dunlap wrote:
>> EXTERNAL EMAIL: Do not click links or open attachments unless you know the content is safe
>>
>> Fix multiple kernel-doc warnings in sama7g5.c. There are several
>> enums and structs that were not identified as such.
>> There are also several anonymous structs (that scripts/kernel-doc
>> has problems with), so add struct names to them.
>>
>> Fixes the following warnings:
>>
>> drivers/clk/at91/sama7g5.c:39: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>>   * PLL clocks identifiers
>> drivers/clk/at91/sama7g5.c:60: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>>   * PLL type identifiers
>> drivers/clk/at91/sama7g5.c:122: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>>   * PLL clocks description
>> drivers/clk/at91/sama7g5.c:289: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>>   * Master clock (MCK[1..4]) description
>> drivers/clk/at91/sama7g5.c:341: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>>   * System clock description
>> drivers/clk/at91/sama7g5.c:365: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>>   * Peripheral clock description
>> drivers/clk/at91/sama7g5.c:453: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>>   * Generic clock description
>> drivers/clk/at91/sama7g5.c:339: warning: Function parameter or member 'ep_chg_id' not described in 'master_clock'
>>
>> Some kernel-doc warnings are still printed, but they are all due to
>> problems in the kernel-doc script (if anyone is interested in playing
>> with some Perl :). These warnings are:
>>
>> sama7g5.c:287: warning: Function parameter or member '{' not described in 'sama7g5_plls'
>> sama7g5.c:287: warning: Function parameter or member '' not described in 'sama7g5_plls'
>> sama7g5.c:287: warning: Function parameter or member '}' not described in 'sama7g5_plls'
>> sama7g5.c:339: warning: Function parameter or member 'sama7g5_mckx' not described in 'master_clock'
>> sama7g5.c:339: warning: Function parameter or member '}' not described in 'master_clock'
>> sama7g5.c:360: warning: Function parameter or member 'sama7g5_systemck' not described in 'system_clock'
>> sama7g5.c:451: warning: Function parameter or member 'sama7g5_periphck' not described in 'periph_clock'
>> sama7g5.c:451: warning: Function parameter or member '' not described in 'periph_clock'
>> sama7g5.c:451: warning: Function parameter or member '}' not described in 'periph_clock'
>> sama7g5.c:841: warning: Function parameter or member 'sama7g5_gck' not described in 'generic_clock'
>> sama7g5.c:841: warning: Function parameter or member '}' not described in 'generic_clock'
> 
> What about keeping only one '*' instead of '**' where necessary as these
> data structures are only local to sama7g5.c file (according to
> Documentation/doc-guide/kernel-doc.rst "Functions and data structures in
> header files which are intended to be used by modules should also have
> kernel-doc comments."). This way all the warnings will be gone.

Sure, that works too.
I'll send an updated patch.

thanks.
-- 
~Randy


^ permalink raw reply	[flat|nested] 8+ messages in thread
* Re: [PATCH] clk/at91: remove kernel-doc warnings in sama7g5.c
@ 2021-08-18  5:32     ` Randy Dunlap
  0 siblings, 0 replies; 8+ messages in thread
From: Randy Dunlap @ 2021-08-18  5:32 UTC (permalink / raw)
  To: Claudiu.Beznea, linux-kernel
  Cc: lkp, mturquette, sboyd, Eugen.Hristev, linux-clk, linux-doc,
	linux-arm-kernel, corbet

On 8/17/21 10:12 PM, Claudiu.Beznea@microchip.com wrote:
> Hi Randy,
> 
> On 10.08.2021 03:54, Randy Dunlap wrote:
>> EXTERNAL EMAIL: Do not click links or open attachments unless you know the content is safe
>>
>> Fix multiple kernel-doc warnings in sama7g5.c. There are several
>> enums and structs that were not identified as such.
>> There are also several anonymous structs (that scripts/kernel-doc
>> has problems with), so add struct names to them.
>>
>> Fixes the following warnings:
>>
>> drivers/clk/at91/sama7g5.c:39: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>>   * PLL clocks identifiers
>> drivers/clk/at91/sama7g5.c:60: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>>   * PLL type identifiers
>> drivers/clk/at91/sama7g5.c:122: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>>   * PLL clocks description
>> drivers/clk/at91/sama7g5.c:289: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>>   * Master clock (MCK[1..4]) description
>> drivers/clk/at91/sama7g5.c:341: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>>   * System clock description
>> drivers/clk/at91/sama7g5.c:365: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>>   * Peripheral clock description
>> drivers/clk/at91/sama7g5.c:453: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
>>   * Generic clock description
>> drivers/clk/at91/sama7g5.c:339: warning: Function parameter or member 'ep_chg_id' not described in 'master_clock'
>>
>> Some kernel-doc warnings are still printed, but they are all due to
>> problems in the kernel-doc script (if anyone is interested in playing
>> with some Perl :). These warnings are:
>>
>> sama7g5.c:287: warning: Function parameter or member '{' not described in 'sama7g5_plls'
>> sama7g5.c:287: warning: Function parameter or member '' not described in 'sama7g5_plls'
>> sama7g5.c:287: warning: Function parameter or member '}' not described in 'sama7g5_plls'
>> sama7g5.c:339: warning: Function parameter or member 'sama7g5_mckx' not described in 'master_clock'
>> sama7g5.c:339: warning: Function parameter or member '}' not described in 'master_clock'
>> sama7g5.c:360: warning: Function parameter or member 'sama7g5_systemck' not described in 'system_clock'
>> sama7g5.c:451: warning: Function parameter or member 'sama7g5_periphck' not described in 'periph_clock'
>> sama7g5.c:451: warning: Function parameter or member '' not described in 'periph_clock'
>> sama7g5.c:451: warning: Function parameter or member '}' not described in 'periph_clock'
>> sama7g5.c:841: warning: Function parameter or member 'sama7g5_gck' not described in 'generic_clock'
>> sama7g5.c:841: warning: Function parameter or member '}' not described in 'generic_clock'
> 
> What about keeping only one '*' instead of '**' where necessary as these
> data structures are only local to sama7g5.c file (according to
> Documentation/doc-guide/kernel-doc.rst "Functions and data structures in
> header files which are intended to be used by modules should also have
> kernel-doc comments."). This way all the warnings will be gone.

Sure, that works too.
I'll send an updated patch.

thanks.
-- 
~Randy


_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

^ permalink raw reply	[flat|nested] 8+ messages in thread
* Re: [PATCH] clk/at91: remove kernel-doc warnings in sama7g5.c
  2021-08-18  5:32     ` Randy Dunlap
@ 2021-08-18  7:20       ` Claudiu.Beznea
  -1 siblings, 0 replies; 8+ messages in thread
From: Claudiu.Beznea @ 2021-08-18  7:20 UTC (permalink / raw)
  To: rdunlap, linux-kernel
  Cc: lkp, mturquette, sboyd, Eugen.Hristev, linux-clk, linux-doc,
	linux-arm-kernel, corbet

On 18.08.2021 08:32, Randy Dunlap wrote:
> EXTERNAL EMAIL: Do not click links or open attachments unless you know the
> content is safe
> 
> On 8/17/21 10:12 PM, Claudiu.Beznea@microchip.com wrote:
>> Hi Randy,
>>
>> On 10.08.2021 03:54, Randy Dunlap wrote:
>>> EXTERNAL EMAIL: Do not click links or open attachments unless you know
>>> the content is safe
>>>
>>> Fix multiple kernel-doc warnings in sama7g5.c. There are several
>>> enums and structs that were not identified as such.
>>> There are also several anonymous structs (that scripts/kernel-doc
>>> has problems with), so add struct names to them.
>>>
>>> Fixes the following warnings:
>>>
>>> drivers/clk/at91/sama7g5.c:39: warning: This comment starts with '/**',
>>> but isn't a kernel-doc comment. Refer
>>> Documentation/doc-guide/kernel-doc.rst
>>>   * PLL clocks identifiers
>>> drivers/clk/at91/sama7g5.c:60: warning: This comment starts with '/**',
>>> but isn't a kernel-doc comment. Refer
>>> Documentation/doc-guide/kernel-doc.rst
>>>   * PLL type identifiers
>>> drivers/clk/at91/sama7g5.c:122: warning: This comment starts with '/**',
>>> but isn't a kernel-doc comment. Refer
>>> Documentation/doc-guide/kernel-doc.rst
>>>   * PLL clocks description
>>> drivers/clk/at91/sama7g5.c:289: warning: This comment starts with '/**',
>>> but isn't a kernel-doc comment. Refer
>>> Documentation/doc-guide/kernel-doc.rst
>>>   * Master clock (MCK[1..4]) description
>>> drivers/clk/at91/sama7g5.c:341: warning: This comment starts with '/**',
>>> but isn't a kernel-doc comment. Refer
>>> Documentation/doc-guide/kernel-doc.rst
>>>   * System clock description
>>> drivers/clk/at91/sama7g5.c:365: warning: This comment starts with '/**',
>>> but isn't a kernel-doc comment. Refer
>>> Documentation/doc-guide/kernel-doc.rst
>>>   * Peripheral clock description
>>> drivers/clk/at91/sama7g5.c:453: warning: This comment starts with '/**',
>>> but isn't a kernel-doc comment. Refer
>>> Documentation/doc-guide/kernel-doc.rst
>>>   * Generic clock description
>>> drivers/clk/at91/sama7g5.c:339: warning: Function parameter or member
>>> 'ep_chg_id' not described in 'master_clock'
>>>
>>> Some kernel-doc warnings are still printed, but they are all due to
>>> problems in the kernel-doc script (if anyone is interested in playing
>>> with some Perl :). These warnings are:
>>>
>>> sama7g5.c:287: warning: Function parameter or member '{' not described
>>> in 'sama7g5_plls'
>>> sama7g5.c:287: warning: Function parameter or member '' not described in
>>> 'sama7g5_plls'
>>> sama7g5.c:287: warning: Function parameter or member '}' not described
>>> in 'sama7g5_plls'
>>> sama7g5.c:339: warning: Function parameter or member 'sama7g5_mckx' not
>>> described in 'master_clock'
>>> sama7g5.c:339: warning: Function parameter or member '}' not described
>>> in 'master_clock'
>>> sama7g5.c:360: warning: Function parameter or member 'sama7g5_systemck'
>>> not described in 'system_clock'
>>> sama7g5.c:451: warning: Function parameter or member 'sama7g5_periphck'
>>> not described in 'periph_clock'
>>> sama7g5.c:451: warning: Function parameter or member '' not described in
>>> 'periph_clock'
>>> sama7g5.c:451: warning: Function parameter or member '}' not described
>>> in 'periph_clock'
>>> sama7g5.c:841: warning: Function parameter or member 'sama7g5_gck' not
>>> described in 'generic_clock'
>>> sama7g5.c:841: warning: Function parameter or member '}' not described
>>> in 'generic_clock'
>>
>> What about keeping only one '*' instead of '**' where necessary as these
>> data structures are only local to sama7g5.c file (according to
>> Documentation/doc-guide/kernel-doc.rst "Functions and data structures in
>> header files which are intended to be used by modules should also have
>> kernel-doc comments."). This way all the warnings will be gone.
> 
> Sure, that works too.
> I'll send an updated patch.

Also, the title should be something like
"clk: at91: sama7g5: <your message>"

> 
> thanks.
> -- 
> ~Randy
> 


^ permalink raw reply	[flat|nested] 8+ messages in thread
* Re: [PATCH] clk/at91: remove kernel-doc warnings in sama7g5.c
@ 2021-08-18  7:20       ` Claudiu.Beznea
  0 siblings, 0 replies; 8+ messages in thread
From: Claudiu.Beznea @ 2021-08-18  7:20 UTC (permalink / raw)
  To: rdunlap, linux-kernel
  Cc: lkp, mturquette, sboyd, Eugen.Hristev, linux-clk, linux-doc,
	linux-arm-kernel, corbet

On 18.08.2021 08:32, Randy Dunlap wrote:
> EXTERNAL EMAIL: Do not click links or open attachments unless you know the
> content is safe
> 
> On 8/17/21 10:12 PM, Claudiu.Beznea@microchip.com wrote:
>> Hi Randy,
>>
>> On 10.08.2021 03:54, Randy Dunlap wrote:
>>> EXTERNAL EMAIL: Do not click links or open attachments unless you know
>>> the content is safe
>>>
>>> Fix multiple kernel-doc warnings in sama7g5.c. There are several
>>> enums and structs that were not identified as such.
>>> There are also several anonymous structs (that scripts/kernel-doc
>>> has problems with), so add struct names to them.
>>>
>>> Fixes the following warnings:
>>>
>>> drivers/clk/at91/sama7g5.c:39: warning: This comment starts with '/**',
>>> but isn't a kernel-doc comment. Refer
>>> Documentation/doc-guide/kernel-doc.rst
>>>   * PLL clocks identifiers
>>> drivers/clk/at91/sama7g5.c:60: warning: This comment starts with '/**',
>>> but isn't a kernel-doc comment. Refer
>>> Documentation/doc-guide/kernel-doc.rst
>>>   * PLL type identifiers
>>> drivers/clk/at91/sama7g5.c:122: warning: This comment starts with '/**',
>>> but isn't a kernel-doc comment. Refer
>>> Documentation/doc-guide/kernel-doc.rst
>>>   * PLL clocks description
>>> drivers/clk/at91/sama7g5.c:289: warning: This comment starts with '/**',
>>> but isn't a kernel-doc comment. Refer
>>> Documentation/doc-guide/kernel-doc.rst
>>>   * Master clock (MCK[1..4]) description
>>> drivers/clk/at91/sama7g5.c:341: warning: This comment starts with '/**',
>>> but isn't a kernel-doc comment. Refer
>>> Documentation/doc-guide/kernel-doc.rst
>>>   * System clock description
>>> drivers/clk/at91/sama7g5.c:365: warning: This comment starts with '/**',
>>> but isn't a kernel-doc comment. Refer
>>> Documentation/doc-guide/kernel-doc.rst
>>>   * Peripheral clock description
>>> drivers/clk/at91/sama7g5.c:453: warning: This comment starts with '/**',
>>> but isn't a kernel-doc comment. Refer
>>> Documentation/doc-guide/kernel-doc.rst
>>>   * Generic clock description
>>> drivers/clk/at91/sama7g5.c:339: warning: Function parameter or member
>>> 'ep_chg_id' not described in 'master_clock'
>>>
>>> Some kernel-doc warnings are still printed, but they are all due to
>>> problems in the kernel-doc script (if anyone is interested in playing
>>> with some Perl :). These warnings are:
>>>
>>> sama7g5.c:287: warning: Function parameter or member '{' not described
>>> in 'sama7g5_plls'
>>> sama7g5.c:287: warning: Function parameter or member '' not described in
>>> 'sama7g5_plls'
>>> sama7g5.c:287: warning: Function parameter or member '}' not described
>>> in 'sama7g5_plls'
>>> sama7g5.c:339: warning: Function parameter or member 'sama7g5_mckx' not
>>> described in 'master_clock'
>>> sama7g5.c:339: warning: Function parameter or member '}' not described
>>> in 'master_clock'
>>> sama7g5.c:360: warning: Function parameter or member 'sama7g5_systemck'
>>> not described in 'system_clock'
>>> sama7g5.c:451: warning: Function parameter or member 'sama7g5_periphck'
>>> not described in 'periph_clock'
>>> sama7g5.c:451: warning: Function parameter or member '' not described in
>>> 'periph_clock'
>>> sama7g5.c:451: warning: Function parameter or member '}' not described
>>> in 'periph_clock'
>>> sama7g5.c:841: warning: Function parameter or member 'sama7g5_gck' not
>>> described in 'generic_clock'
>>> sama7g5.c:841: warning: Function parameter or member '}' not described
>>> in 'generic_clock'
>>
>> What about keeping only one '*' instead of '**' where necessary as these
>> data structures are only local to sama7g5.c file (according to
>> Documentation/doc-guide/kernel-doc.rst "Functions and data structures in
>> header files which are intended to be used by modules should also have
>> kernel-doc comments."). This way all the warnings will be gone.
> 
> Sure, that works too.
> I'll send an updated patch.

Also, the title should be something like
"clk: at91: sama7g5: <your message>"

> 
> thanks.
> -- 
> ~Randy
> 

_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

^ permalink raw reply	[flat|nested] 8+ messages in thread
end of thread, other threads:[~2021-08-18  7:23 UTC | newest]

Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-08-10  0:54 [PATCH] clk/at91: remove kernel-doc warnings in sama7g5.c Randy Dunlap
2021-08-10  0:54 ` Randy Dunlap
2021-08-18  5:12 ` Claudiu.Beznea
2021-08-18  5:12   ` Claudiu.Beznea
2021-08-18  5:32   ` Randy Dunlap
2021-08-18  5:32     ` Randy Dunlap
2021-08-18  7:20     ` Claudiu.Beznea
2021-08-18  7:20       ` Claudiu.Beznea

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.