diff mbox series

scripts/kernel-doc: restore warning for Excess struct/union

Message ID 20231214070200.24405-1-rdunlap@infradead.org
State New
Headers
Series scripts/kernel-doc: restore warning for Excess struct/union |

Commit Message

Randy Dunlap Dec. 14, 2023, 7:02 a.m. UTC 
  The warning for Excess struct or union member description was
removed when the $nested parameter of check_sections() was removed.
This causes some kernel-doc notation warnings to be missed.

Recently the kernel test robot somehow reported an Excess member. The
code in kernel-doc has not issued that warning since kernel v4.16, so I
don't know how the robot did it. (See the Link for the report.)

  drivers/net/wireless/intel/iwlwifi/fw/dbg.c:86: warning: Excess struct/union/enum/typedef member 'trans_len' description in 'iwl_fw_dump_ptrs'

I patched that warning away even though I could not reproduce the
warning from kernel-doc. The warning should be issued for extraneous
struct member or union member description, so restore it.

Fixes: 1081de2d2f91 ("scripts: kernel-doc: get rid of $nested parameter")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/all/202312060810.QT9zourt-lkp@intel.com/
Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
---
 scripts/kernel-doc |    7 +++++++
 1 file changed, 7 insertions(+)

Comments

Randy Dunlap Dec. 14, 2023, 7:05 a.m. UTC | #1 
(correcting Mauro's email address)


On 12/13/23 23:02, Randy Dunlap wrote:
> The warning for Excess struct or union member description was
> removed when the $nested parameter of check_sections() was removed.
> This causes some kernel-doc notation warnings to be missed.
> 
> Recently the kernel test robot somehow reported an Excess member. The
> code in kernel-doc has not issued that warning since kernel v4.16, so I
> don't know how the robot did it. (See the Link for the report.)
> 
>   drivers/net/wireless/intel/iwlwifi/fw/dbg.c:86: warning: Excess struct/union/enum/typedef member 'trans_len' description in 'iwl_fw_dump_ptrs'
> 
> I patched that warning away even though I could not reproduce the
> warning from kernel-doc. The warning should be issued for extraneous
> struct member or union member description, so restore it.
> 
> Fixes: 1081de2d2f91 ("scripts: kernel-doc: get rid of $nested parameter")
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Link: https://lore.kernel.org/all/202312060810.QT9zourt-lkp@intel.com/
> Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: linux-doc@vger.kernel.org
> ---
>  scripts/kernel-doc |    7 +++++++
>  1 file changed, 7 insertions(+)
> 
> diff -- a/scripts/kernel-doc b/scripts/kernel-doc
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -1659,6 +1659,13 @@ sub check_sections($$$$$) {
>  					"'$sects[$sx]' " .
>  					"description in '$decl_name'\n");
>  			}
> +			elsif (($decl_type eq "struct") or
> +		       	       ($decl_type eq "union")) {
> +				emit_warning("${file}:$.",
> +					"Excess $decl_type member " .
> +					"'$sects[$sx]' " .
> +					"description in '$decl_name'\n");
> +			}
>  		}
>  	}
>  }
Kees Cook Dec. 15, 2023, 1:02 a.m. UTC | #2 
On Wed, Dec 13, 2023 at 11:05:42PM -0800, Randy Dunlap wrote:
> (correcting Mauro's email address)
> 
> 
> On 12/13/23 23:02, Randy Dunlap wrote:
> > The warning for Excess struct or union member description was
> > removed when the $nested parameter of check_sections() was removed.
> > This causes some kernel-doc notation warnings to be missed.
> > 
> > Recently the kernel test robot somehow reported an Excess member. The
> > code in kernel-doc has not issued that warning since kernel v4.16, so I
> > don't know how the robot did it. (See the Link for the report.)
> > 
> >   drivers/net/wireless/intel/iwlwifi/fw/dbg.c:86: warning: Excess struct/union/enum/typedef member 'trans_len' description in 'iwl_fw_dump_ptrs'
> > 
> > I patched that warning away even though I could not reproduce the
> > warning from kernel-doc. The warning should be issued for extraneous
> > struct member or union member description, so restore it.
> > 
> > Fixes: 1081de2d2f91 ("scripts: kernel-doc: get rid of $nested parameter")
> > Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> > Link: https://lore.kernel.org/all/202312060810.QT9zourt-lkp@intel.com/
> > Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > Cc: Jonathan Corbet <corbet@lwn.net>
> > Cc: linux-doc@vger.kernel.org
> > ---
> >  scripts/kernel-doc |    7 +++++++
> >  1 file changed, 7 insertions(+)
> > 
> > diff -- a/scripts/kernel-doc b/scripts/kernel-doc
> > --- a/scripts/kernel-doc
> > +++ b/scripts/kernel-doc
> > @@ -1659,6 +1659,13 @@ sub check_sections($$$$$) {
> >  					"'$sects[$sx]' " .
> >  					"description in '$decl_name'\n");
> >  			}
> > +			elsif (($decl_type eq "struct") or
> > +		       	       ($decl_type eq "union")) {
> > +				emit_warning("${file}:$.",
> > +					"Excess $decl_type member " .
> > +					"'$sects[$sx]' " .
> > +					"description in '$decl_name'\n");
> > +			}
> >  		}
> >  	}
> >  }

Yes, please!

Reviewed-by: Kees Cook <keescook@chromium.org>
kernel test robot Dec. 15, 2023, 5:35 a.m. UTC | #3 
Hi Randy,

kernel test robot noticed the following build warnings:

[auto build test WARNING on lwn/docs-next]
[also build test WARNING on linus/master v6.7-rc5 next-20231214]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]

url:    https://github.com/intel-lab-lkp/linux/commits/Randy-Dunlap/scripts-kernel-doc-restore-warning-for-Excess-struct-union/20231214-150722
base:   git://git.lwn.net/linux.git docs-next
patch link:    https://lore.kernel.org/r/20231214070200.24405-1-rdunlap%40infradead.org
patch subject: [PATCH] scripts/kernel-doc: restore warning for Excess struct/union
config: arm-randconfig-r081-20231214 (https://download.01.org/0day-ci/archive/20231215/202312151356.OZmUHKRx-lkp@intel.com/config)
compiler: arm-linux-gnueabi-gcc (GCC) 13.2.0
reproduce (this is a W=1 build): (https://download.01.org/0day-ci/archive/20231215/202312151356.OZmUHKRx-lkp@intel.com/reproduce)

If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/oe-kbuild-all/202312151356.OZmUHKRx-lkp@intel.com/

All warnings (new ones prefixed by >>):

>> drivers/gpio/gpio-syscon.c:46: warning: Excess struct member 'compatible' description in 'syscon_gpio_data'
--
>> drivers/gpio/gpio-xilinx.c:75: warning: Excess struct member 'irqchip' description in 'xgpio_instance'
--
>> net/tipc/link.c:228: warning: Excess struct member 'media_addr' description in 'tipc_link'
>> net/tipc/link.c:228: warning: Excess struct member 'timer' description in 'tipc_link'
>> net/tipc/link.c:228: warning: Excess struct member 'refcnt' description in 'tipc_link'
>> net/tipc/link.c:228: warning: Excess struct member 'proto_msg' description in 'tipc_link'
>> net/tipc/link.c:228: warning: Excess struct member 'pmsg' description in 'tipc_link'
>> net/tipc/link.c:228: warning: Excess struct member 'backlog_limit' description in 'tipc_link'
>> net/tipc/link.c:228: warning: Excess struct member 'exp_msg_count' description in 'tipc_link'
>> net/tipc/link.c:228: warning: Excess struct member 'reset_rcv_checkpt' description in 'tipc_link'
>> net/tipc/link.c:228: warning: Excess struct member 'transmitq' description in 'tipc_link'
>> net/tipc/link.c:228: warning: Excess struct member 'snt_nxt' description in 'tipc_link'
>> net/tipc/link.c:228: warning: Excess struct member 'deferred_queue' description in 'tipc_link'
>> net/tipc/link.c:228: warning: Excess struct member 'unacked_window' description in 'tipc_link'
>> net/tipc/link.c:228: warning: Excess struct member 'next_out' description in 'tipc_link'
>> net/tipc/link.c:228: warning: Excess struct member 'long_msg_seq_no' description in 'tipc_link'
>> net/tipc/link.c:228: warning: Excess struct member 'bc_rcvr' description in 'tipc_link'
--
>> net/tipc/node.c:150: warning: Excess struct member 'inputq' description in 'tipc_node'
>> net/tipc/node.c:150: warning: Excess struct member 'namedq' description in 'tipc_node'
--
>> net/tipc/socket.c:143: warning: Excess struct member 'blocking_link' description in 'tipc_sock'
--
>> drivers/hte/hte.c:90: warning: Excess struct member 'ei' description in 'hte_device'
--
>> drivers/i2c/i2c-atr.c:98: warning: Excess struct member 'adapter' description in 'i2c_atr'
--
>> drivers/leds/leds-lm3697.c:93: warning: Excess struct member 'leds' description in 'lm3697'
--
>> drivers/leds/leds-mlxreg.c:42: warning: Excess struct member 'led_data' description in 'mlxreg_led_data'
--
>> drivers/of/property.c:1240: warning: Excess struct member 'parse_prop.np' description in 'supplier_bindings'
>> drivers/of/property.c:1240: warning: Excess struct member 'parse_prop.prop_name' description in 'supplier_bindings'
>> drivers/of/property.c:1240: warning: Excess struct member 'parse_prop.index' description in 'supplier_bindings'
--
>> drivers/reset/core.c:64: warning: Excess struct member 'rstc' description in 'reset_control_array'
..


vim +46 drivers/gpio/gpio-syscon.c

6a8a0c1d87377c Alexander Shiyan  2014-03-11  23  
6a8a0c1d87377c Alexander Shiyan  2014-03-11  24  /**
6a8a0c1d87377c Alexander Shiyan  2014-03-11  25   * struct syscon_gpio_data - Configuration for the device.
5f3beb67b5d1c5 Lee Jones         2020-06-30  26   * @compatible:		SYSCON driver compatible string.
5f3beb67b5d1c5 Lee Jones         2020-06-30  27   * @flags:		Set of GPIO_SYSCON_FEAT_ flags:
6a8a0c1d87377c Alexander Shiyan  2014-03-11  28   *			GPIO_SYSCON_FEAT_IN:	GPIOs supports input,
6a8a0c1d87377c Alexander Shiyan  2014-03-11  29   *			GPIO_SYSCON_FEAT_OUT:	GPIOs supports output,
6a8a0c1d87377c Alexander Shiyan  2014-03-11  30   *			GPIO_SYSCON_FEAT_DIR:	GPIOs supports switch direction.
5f3beb67b5d1c5 Lee Jones         2020-06-30  31   * @bit_count:		Number of bits used as GPIOs.
5f3beb67b5d1c5 Lee Jones         2020-06-30  32   * @dat_bit_offset:	Offset (in bits) to the first GPIO bit.
5f3beb67b5d1c5 Lee Jones         2020-06-30  33   * @dir_bit_offset:	Optional offset (in bits) to the first bit to switch
6a8a0c1d87377c Alexander Shiyan  2014-03-11  34   *			GPIO direction (Used with GPIO_SYSCON_FEAT_DIR flag).
5f3beb67b5d1c5 Lee Jones         2020-06-30  35   * @set:		HW specific callback to assigns output value
2c341d62eb4b69 Grygorii Strashko 2014-09-03  36   *			for signal "offset"
6a8a0c1d87377c Alexander Shiyan  2014-03-11  37   */
6a8a0c1d87377c Alexander Shiyan  2014-03-11  38  
6a8a0c1d87377c Alexander Shiyan  2014-03-11  39  struct syscon_gpio_data {
6a8a0c1d87377c Alexander Shiyan  2014-03-11  40  	unsigned int	flags;
6a8a0c1d87377c Alexander Shiyan  2014-03-11  41  	unsigned int	bit_count;
6a8a0c1d87377c Alexander Shiyan  2014-03-11  42  	unsigned int	dat_bit_offset;
6a8a0c1d87377c Alexander Shiyan  2014-03-11  43  	unsigned int	dir_bit_offset;
2c341d62eb4b69 Grygorii Strashko 2014-09-03  44  	void		(*set)(struct gpio_chip *chip,
2c341d62eb4b69 Grygorii Strashko 2014-09-03  45  			       unsigned offset, int value);
6a8a0c1d87377c Alexander Shiyan  2014-03-11 @46  };
6a8a0c1d87377c Alexander Shiyan  2014-03-11  47
Randy Dunlap Dec. 15, 2023, 5:38 a.m. UTC | #4 
On 12/14/23 21:35, kernel test robot wrote:
> Hi Randy,
> 
> kernel test robot noticed the following build warnings:
> 

That's great. Thanks.

> [auto build test WARNING on lwn/docs-next]
> [also build test WARNING on linus/master v6.7-rc5 next-20231214]
> [If your patch is applied to the wrong git tree, kindly drop us a note.
> And when submitting patch, we suggest to use '--base' as documented in
> https://git-scm.com/docs/git-format-patch#_base_tree_information]
> 
> url:    https://github.com/intel-lab-lkp/linux/commits/Randy-Dunlap/scripts-kernel-doc-restore-warning-for-Excess-struct-union/20231214-150722
> base:   git://git.lwn.net/linux.git docs-next
> patch link:    https://lore.kernel.org/r/20231214070200.24405-1-rdunlap%40infradead.org
> patch subject: [PATCH] scripts/kernel-doc: restore warning for Excess struct/union
> config: arm-randconfig-r081-20231214 (https://download.01.org/0day-ci/archive/20231215/202312151356.OZmUHKRx-lkp@intel.com/config)
> compiler: arm-linux-gnueabi-gcc (GCC) 13.2.0
> reproduce (this is a W=1 build): (https://download.01.org/0day-ci/archive/20231215/202312151356.OZmUHKRx-lkp@intel.com/reproduce)
> 
> If you fix the issue in a separate patch/commit (i.e. not just a new version of
> the same patch/commit), kindly add following tags
> | Reported-by: kernel test robot <lkp@intel.com>
> | Closes: https://lore.kernel.org/oe-kbuild-all/202312151356.OZmUHKRx-lkp@intel.com/
> 
> All warnings (new ones prefixed by >>):
> 
>>> drivers/gpio/gpio-syscon.c:46: warning: Excess struct member 'compatible' description in 'syscon_gpio_data'
> --
>>> drivers/gpio/gpio-xilinx.c:75: warning: Excess struct member 'irqchip' description in 'xgpio_instance'
> --
>>> net/tipc/link.c:228: warning: Excess struct member 'media_addr' description in 'tipc_link'
>>> net/tipc/link.c:228: warning: Excess struct member 'timer' description in 'tipc_link'
>>> net/tipc/link.c:228: warning: Excess struct member 'refcnt' description in 'tipc_link'
>>> net/tipc/link.c:228: warning: Excess struct member 'proto_msg' description in 'tipc_link'
>>> net/tipc/link.c:228: warning: Excess struct member 'pmsg' description in 'tipc_link'
>>> net/tipc/link.c:228: warning: Excess struct member 'backlog_limit' description in 'tipc_link'
>>> net/tipc/link.c:228: warning: Excess struct member 'exp_msg_count' description in 'tipc_link'
>>> net/tipc/link.c:228: warning: Excess struct member 'reset_rcv_checkpt' description in 'tipc_link'
>>> net/tipc/link.c:228: warning: Excess struct member 'transmitq' description in 'tipc_link'
>>> net/tipc/link.c:228: warning: Excess struct member 'snt_nxt' description in 'tipc_link'
>>> net/tipc/link.c:228: warning: Excess struct member 'deferred_queue' description in 'tipc_link'
>>> net/tipc/link.c:228: warning: Excess struct member 'unacked_window' description in 'tipc_link'
>>> net/tipc/link.c:228: warning: Excess struct member 'next_out' description in 'tipc_link'
>>> net/tipc/link.c:228: warning: Excess struct member 'long_msg_seq_no' description in 'tipc_link'
>>> net/tipc/link.c:228: warning: Excess struct member 'bc_rcvr' description in 'tipc_link'
> --
>>> net/tipc/node.c:150: warning: Excess struct member 'inputq' description in 'tipc_node'
>>> net/tipc/node.c:150: warning: Excess struct member 'namedq' description in 'tipc_node'
> --
>>> net/tipc/socket.c:143: warning: Excess struct member 'blocking_link' description in 'tipc_sock'
> --
>>> drivers/hte/hte.c:90: warning: Excess struct member 'ei' description in 'hte_device'
> --
>>> drivers/i2c/i2c-atr.c:98: warning: Excess struct member 'adapter' description in 'i2c_atr'
> --
>>> drivers/leds/leds-lm3697.c:93: warning: Excess struct member 'leds' description in 'lm3697'
> --
>>> drivers/leds/leds-mlxreg.c:42: warning: Excess struct member 'led_data' description in 'mlxreg_led_data'
> --
>>> drivers/of/property.c:1240: warning: Excess struct member 'parse_prop.np' description in 'supplier_bindings'
>>> drivers/of/property.c:1240: warning: Excess struct member 'parse_prop.prop_name' description in 'supplier_bindings'
>>> drivers/of/property.c:1240: warning: Excess struct member 'parse_prop.index' description in 'supplier_bindings'
> --
>>> drivers/reset/core.c:64: warning: Excess struct member 'rstc' description in 'reset_control_array'
> ..
> 
> 
> vim +46 drivers/gpio/gpio-syscon.c
> 
> 6a8a0c1d87377c Alexander Shiyan  2014-03-11  23  
> 6a8a0c1d87377c Alexander Shiyan  2014-03-11  24  /**
> 6a8a0c1d87377c Alexander Shiyan  2014-03-11  25   * struct syscon_gpio_data - Configuration for the device.
> 5f3beb67b5d1c5 Lee Jones         2020-06-30  26   * @compatible:		SYSCON driver compatible string.
> 5f3beb67b5d1c5 Lee Jones         2020-06-30  27   * @flags:		Set of GPIO_SYSCON_FEAT_ flags:
> 6a8a0c1d87377c Alexander Shiyan  2014-03-11  28   *			GPIO_SYSCON_FEAT_IN:	GPIOs supports input,
> 6a8a0c1d87377c Alexander Shiyan  2014-03-11  29   *			GPIO_SYSCON_FEAT_OUT:	GPIOs supports output,
> 6a8a0c1d87377c Alexander Shiyan  2014-03-11  30   *			GPIO_SYSCON_FEAT_DIR:	GPIOs supports switch direction.
> 5f3beb67b5d1c5 Lee Jones         2020-06-30  31   * @bit_count:		Number of bits used as GPIOs.
> 5f3beb67b5d1c5 Lee Jones         2020-06-30  32   * @dat_bit_offset:	Offset (in bits) to the first GPIO bit.
> 5f3beb67b5d1c5 Lee Jones         2020-06-30  33   * @dir_bit_offset:	Optional offset (in bits) to the first bit to switch
> 6a8a0c1d87377c Alexander Shiyan  2014-03-11  34   *			GPIO direction (Used with GPIO_SYSCON_FEAT_DIR flag).
> 5f3beb67b5d1c5 Lee Jones         2020-06-30  35   * @set:		HW specific callback to assigns output value
> 2c341d62eb4b69 Grygorii Strashko 2014-09-03  36   *			for signal "offset"
> 6a8a0c1d87377c Alexander Shiyan  2014-03-11  37   */
> 6a8a0c1d87377c Alexander Shiyan  2014-03-11  38  
> 6a8a0c1d87377c Alexander Shiyan  2014-03-11  39  struct syscon_gpio_data {
> 6a8a0c1d87377c Alexander Shiyan  2014-03-11  40  	unsigned int	flags;
> 6a8a0c1d87377c Alexander Shiyan  2014-03-11  41  	unsigned int	bit_count;
> 6a8a0c1d87377c Alexander Shiyan  2014-03-11  42  	unsigned int	dat_bit_offset;
> 6a8a0c1d87377c Alexander Shiyan  2014-03-11  43  	unsigned int	dir_bit_offset;
> 2c341d62eb4b69 Grygorii Strashko 2014-09-03  44  	void		(*set)(struct gpio_chip *chip,
> 2c341d62eb4b69 Grygorii Strashko 2014-09-03  45  			       unsigned offset, int value);
> 6a8a0c1d87377c Alexander Shiyan  2014-03-11 @46  };
> 6a8a0c1d87377c Alexander Shiyan  2014-03-11  47  
>
kernel test robot Dec. 15, 2023, 6:48 a.m. UTC | #5 
Hi Randy,

kernel test robot noticed the following build warnings:

[auto build test WARNING on lwn/docs-next]
[also build test WARNING on linus/master v6.7-rc5 next-20231215]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]

url:    https://github.com/intel-lab-lkp/linux/commits/Randy-Dunlap/scripts-kernel-doc-restore-warning-for-Excess-struct-union/20231214-150722
base:   git://git.lwn.net/linux.git docs-next
patch link:    https://lore.kernel.org/r/20231214070200.24405-1-rdunlap%40infradead.org
patch subject: [PATCH] scripts/kernel-doc: restore warning for Excess struct/union
config: arm64-defconfig (https://download.01.org/0day-ci/archive/20231215/202312151453.AaH01Gw5-lkp@intel.com/config)
compiler: aarch64-linux-gcc (GCC) 13.2.0
reproduce (this is a W=1 build): (https://download.01.org/0day-ci/archive/20231215/202312151453.AaH01Gw5-lkp@intel.com/reproduce)

If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/oe-kbuild-all/202312151453.AaH01Gw5-lkp@intel.com/

All warnings (new ones prefixed by >>):

>> drivers/mailbox/zynqmp-ipi-mailbox.c:92: warning: Excess struct member 'irq' description in 'zynqmp_ipi_mbox'
>> drivers/mailbox/zynqmp-ipi-mailbox.c:112: warning: Excess struct member 'ipi_mboxes' description in 'zynqmp_ipi_pdata'
--
>> drivers/pinctrl/pinctrl-zynqmp.c:60: warning: Excess struct member 'node' description in 'zynqmp_pmux_function'
--
>> drivers/pwm/pwm-mediatek.c:60: warning: Excess struct member 'clk_freq' description in 'pwm_mediatek_chip'
--
>> drivers/net/ipa/ipa_power.c:71: warning: Excess struct member 'interconnect' description in 'ipa_power'
--
>> drivers/media/platform/mediatek/vcodec/decoder/vdec/vdec_vp8_req_if.c:57: warning: Excess struct member 'wait_key_frame' description in 'vdec_vp8_slice_info'
--
>> drivers/media/platform/mediatek/vcodec/decoder/vdec/vdec_vp9_req_lat_if.c:166: warning: Excess struct member 'mv_joint' description in 'vdec_vp9_slice_counts_map'


vim +92 drivers/mailbox/zynqmp-ipi-mailbox.c

4981b82ba2ff87d Wendy Liang 2019-02-21   74  
4981b82ba2ff87d Wendy Liang 2019-02-21   75  /**
4981b82ba2ff87d Wendy Liang 2019-02-21   76   * struct zynqmp_ipi_mbox - Description of a ZynqMP IPI mailbox
4981b82ba2ff87d Wendy Liang 2019-02-21   77   *                          platform data.
4981b82ba2ff87d Wendy Liang 2019-02-21   78   * @pdata:		  pointer to the IPI private data
4981b82ba2ff87d Wendy Liang 2019-02-21   79   * @dev:                  device pointer corresponding to the Xilinx ZynqMP
4981b82ba2ff87d Wendy Liang 2019-02-21   80   *                        IPI mailbox
4981b82ba2ff87d Wendy Liang 2019-02-21   81   * @remote_id:            remote IPI agent ID
4981b82ba2ff87d Wendy Liang 2019-02-21   82   * @mbox:                 mailbox Controller
4981b82ba2ff87d Wendy Liang 2019-02-21   83   * @mchans:               array for channels, tx channel and rx channel.
4981b82ba2ff87d Wendy Liang 2019-02-21   84   * @irq:                  IPI agent interrupt ID
4981b82ba2ff87d Wendy Liang 2019-02-21   85   */
4981b82ba2ff87d Wendy Liang 2019-02-21   86  struct zynqmp_ipi_mbox {
4981b82ba2ff87d Wendy Liang 2019-02-21   87  	struct zynqmp_ipi_pdata *pdata;
4981b82ba2ff87d Wendy Liang 2019-02-21   88  	struct device dev;
4981b82ba2ff87d Wendy Liang 2019-02-21   89  	u32 remote_id;
4981b82ba2ff87d Wendy Liang 2019-02-21   90  	struct mbox_controller mbox;
4981b82ba2ff87d Wendy Liang 2019-02-21   91  	struct zynqmp_ipi_mchan mchans[2];
4981b82ba2ff87d Wendy Liang 2019-02-21  @92  };
4981b82ba2ff87d Wendy Liang 2019-02-21   93  
4981b82ba2ff87d Wendy Liang 2019-02-21   94  /**
4981b82ba2ff87d Wendy Liang 2019-02-21   95   * struct zynqmp_ipi_pdata - Description of z ZynqMP IPI agent platform data.
4981b82ba2ff87d Wendy Liang 2019-02-21   96   *
4981b82ba2ff87d Wendy Liang 2019-02-21   97   * @dev:                  device pointer corresponding to the Xilinx ZynqMP
4981b82ba2ff87d Wendy Liang 2019-02-21   98   *                        IPI agent
4981b82ba2ff87d Wendy Liang 2019-02-21   99   * @irq:                  IPI agent interrupt ID
4981b82ba2ff87d Wendy Liang 2019-02-21  100   * @method:               IPI SMC or HVC is going to be used
4981b82ba2ff87d Wendy Liang 2019-02-21  101   * @local_id:             local IPI agent ID
4981b82ba2ff87d Wendy Liang 2019-02-21  102   * @num_mboxes:           number of mailboxes of this IPI agent
4981b82ba2ff87d Wendy Liang 2019-02-21  103   * @ipi_mboxes:           IPI mailboxes of this IPI agent
4981b82ba2ff87d Wendy Liang 2019-02-21  104   */
4981b82ba2ff87d Wendy Liang 2019-02-21  105  struct zynqmp_ipi_pdata {
4981b82ba2ff87d Wendy Liang 2019-02-21  106  	struct device *dev;
4981b82ba2ff87d Wendy Liang 2019-02-21  107  	int irq;
4981b82ba2ff87d Wendy Liang 2019-02-21  108  	unsigned int method;
4981b82ba2ff87d Wendy Liang 2019-02-21  109  	u32 local_id;
4981b82ba2ff87d Wendy Liang 2019-02-21  110  	int num_mboxes;
c5225cd073c65a6 Kees Cook   2023-09-22  111  	struct zynqmp_ipi_mbox ipi_mboxes[] __counted_by(num_mboxes);
4981b82ba2ff87d Wendy Liang 2019-02-21 @112  };
4981b82ba2ff87d Wendy Liang 2019-02-21  113
Jonathan Corbet Dec. 15, 2023, 4:28 p.m. UTC | #6 
Randy Dunlap <rdunlap@infradead.org> writes:

> The warning for Excess struct or union member description was
> removed when the $nested parameter of check_sections() was removed.
> This causes some kernel-doc notation warnings to be missed.
>
> Recently the kernel test robot somehow reported an Excess member. The
> code in kernel-doc has not issued that warning since kernel v4.16, so I
> don't know how the robot did it. (See the Link for the report.)
>
>   drivers/net/wireless/intel/iwlwifi/fw/dbg.c:86: warning: Excess struct/union/enum/typedef member 'trans_len' description in 'iwl_fw_dump_ptrs'
>
> I patched that warning away even though I could not reproduce the
> warning from kernel-doc. The warning should be issued for extraneous
> struct member or union member description, so restore it.
>
> Fixes: 1081de2d2f91 ("scripts: kernel-doc: get rid of $nested parameter")
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Link: https://lore.kernel.org/all/202312060810.QT9zourt-lkp@intel.com/
> Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: linux-doc@vger.kernel.org
> ---
>  scripts/kernel-doc |    7 +++++++
>  1 file changed, 7 insertions(+)

*sigh*

This adds nearly 600 new warnings.  Anybody gonna help fix them?

Of course, most of them are duplicates.  Someday it would be really nice
if we could find a way to only emit each warning once.

Anyway, I've applied it.

Thanks,

jon
Vegard Nossum Dec. 21, 2023, 1:48 p.m. UTC | #7 
On 15/12/2023 17:28, Jonathan Corbet wrote:
> *sigh*
> 
> This adds nearly 600 new warnings.  Anybody gonna help fix them?

I think in the vast majority of the cases the fix will be to just remove
the offending line from the kerneldoc, so it's not particularly
difficult, mostly just overhead from the patch preparation/submission
process.

I'd be happy to take a stab at it -- I think we could even script most
of it. Respond here, I guess, if anybody else wants to do some so we can
split it up.

On a related note, it might be useful to have some kind of "status page"
somewhere on the web for the docs where you can see a list of unresolved
documentation warnings in mainline/docs-next/next without having to do a
local build first (as a way to solicit contributions).


Vegard
Jonathan Corbet Dec. 21, 2023, 3:20 p.m. UTC | #8 
Vegard Nossum <vegard.nossum@oracle.com> writes:

> On 15/12/2023 17:28, Jonathan Corbet wrote:
>> *sigh*
>> 
>> This adds nearly 600 new warnings.  Anybody gonna help fix them?
>
> I think in the vast majority of the cases the fix will be to just remove
> the offending line from the kerneldoc, so it's not particularly
> difficult, mostly just overhead from the patch preparation/submission
> process.
>
> I'd be happy to take a stab at it -- I think we could even script most
> of it. Respond here, I guess, if anybody else wants to do some so we can
> split it up.

It's mostly done; I've gotten it down to under 200 and sent patches to
make the changes.  Randy is working on it too, I know.  It's not always
just deletion, but the fixes are usually pretty straightforward.

> On a related note, it might be useful to have some kind of "status page"
> somewhere on the web for the docs where you can see a list of unresolved
> documentation warnings in mainline/docs-next/next without having to do a
> local build first (as a way to solicit contributions).

I suppose, but how do you know you've properly addressed the warning if
you don't do a build afterward?  I don't see that saving a whole lot of
effort, but maybe I'm missing something?

Thanks,

jon
Vegard Nossum Dec. 21, 2023, 4:26 p.m. UTC | #9 
On 21/12/2023 16:20, Jonathan Corbet wrote:
> It's mostly done; I've gotten it down to under 200 and sent patches to
> make the changes.  Randy is working on it too, I know.  It's not always
> just deletion, but the fixes are usually pretty straightforward.

Ah, cool. Will leave it to you, then.

>> On a related note, it might be useful to have some kind of "status page"
>> somewhere on the web for the docs where you can see a list of unresolved
>> documentation warnings in mainline/docs-next/next without having to do a
>> local build first (as a way to solicit contributions).
> 
> I suppose, but how do you know you've properly addressed the warning if
> you don't do a build afterward?  I don't see that saving a whole lot of
> effort, but maybe I'm missing something?

You would definitely have to do local builds too, it's just about
raising awareness of remaining issues and lowering the barrier for
drive-by contributors to picking something to work on. I can only speak
for myself but I find it easier to go look at a list of known problems
than initiating a docs build and waiting for it to come back.

Syzbot has monthly per-subsystem reports now (since ~March, AFAICT):

https://lore.kernel.org/all/0000000000007fbf7a060cc67998@google.com/

A monthly email is maybe even better than what I suggested.

Anyway, I'll try something out, we can see how it works.


Vegard
Randy Dunlap Dec. 22, 2023, 8:11 p.m. UTC | #10 
On 12/21/23 07:20, Jonathan Corbet wrote:
> Vegard Nossum <vegard.nossum@oracle.com> writes:
> 
>> On 15/12/2023 17:28, Jonathan Corbet wrote:
>>> *sigh*
>>>
>>> This adds nearly 600 new warnings.  Anybody gonna help fix them?
>>
>> I think in the vast majority of the cases the fix will be to just remove
>> the offending line from the kerneldoc, so it's not particularly
>> difficult, mostly just overhead from the patch preparation/submission
>> process.
>>
>> I'd be happy to take a stab at it -- I think we could even script most
>> of it. Respond here, I guess, if anybody else wants to do some so we can
>> split it up.
> 
> It's mostly done; I've gotten it down to under 200 and sent patches to
> make the changes.  Randy is working on it too, I know.  It's not always
> just deletion, but the fixes are usually pretty straightforward.
> 

I'm still seeing lots of Excess warnings from
  include/crypto/hash.h
  include/crypto/skcipher.h
  drivers/gpu/drm/*  (several files there have warnings)

I would be happy to see Vegard's help on this - unless Jon has already
addressed those warnings.

>> On a related note, it might be useful to have some kind of "status page"
>> somewhere on the web for the docs where you can see a list of unresolved
>> documentation warnings in mainline/docs-next/next without having to do a
>> local build first (as a way to solicit contributions).
> 
> I suppose, but how do you know you've properly addressed the warning if
> you don't do a build afterward?  I don't see that saving a whole lot of
> effort, but maybe I'm missing something?

Thanks.
Jonathan Corbet Dec. 22, 2023, 11:54 p.m. UTC | #11 
Randy Dunlap <rdunlap@infradead.org> writes:

> On 12/21/23 07:20, Jonathan Corbet wrote:
>> Vegard Nossum <vegard.nossum@oracle.com> writes:
>> 
>>> On 15/12/2023 17:28, Jonathan Corbet wrote:
>>>> *sigh*
>>>>
>>>> This adds nearly 600 new warnings.  Anybody gonna help fix them?
>>>
>>> I think in the vast majority of the cases the fix will be to just remove
>>> the offending line from the kerneldoc, so it's not particularly
>>> difficult, mostly just overhead from the patch preparation/submission
>>> process.
>>>
>>> I'd be happy to take a stab at it -- I think we could even script most
>>> of it. Respond here, I guess, if anybody else wants to do some so we can
>>> split it up.
>> 
>> It's mostly done; I've gotten it down to under 200 and sent patches to
>> make the changes.  Randy is working on it too, I know.  It's not always
>> just deletion, but the fixes are usually pretty straightforward.
>> 
>
> I'm still seeing lots of Excess warnings from
>   include/crypto/hash.h
>   include/crypto/skcipher.h
>   drivers/gpu/drm/*  (several files there have warnings)
>
> I would be happy to see Vegard's help on this - unless Jon has already
> addressed those warnings.

Nope, I've not gone there and won't manage it before sometime next week
at best.  I'd be delighted if somebody waded into those warnings.

Thanks,

jon
diff mbox series

Patch

diff -- a/scripts/kernel-doc b/scripts/kernel-doc
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1659,6 +1659,13 @@  sub check_sections($$$$$) {
 					"'$sects[$sx]' " .
 					"description in '$decl_name'\n");
 			}
+			elsif (($decl_type eq "struct") or
+		       	       ($decl_type eq "union")) {
+				emit_warning("${file}:$.",
+					"Excess $decl_type member " .
+					"'$sects[$sx]' " .
+					"description in '$decl_name'\n");
+			}
 		}
 	}
 }