| Message ID | 20210810005431.22007-1-rdunlap@infradead.org (mailing list archive) |
|---|---|
| State | Changes Requested, archived |
| Headers | show |
| Series | clk/at91: remove kernel-doc warnings in sama7g5.c | expand |
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]; >
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.
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-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];
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(-)