Re: [PATCH net-next] sfc: fix stale kernel-doc member names in net_driver.h

[Simon Horman <horms@kernel.org>]

On Sat, Oct 03, 2026 at 11:24:41AM +0530, Arnav Kapoor wrote:
> Several kernel-doc comments in net_driver.h describe struct members that
> have since been renamed or removed, and the EFX_MAX_FRAME_LEN() comment
> is separated from the macro by the EFX_FRAME_PAD define. kernel-doc
> reports:
> 
>   Excess struct member 'state' description in 'efx_channel'
>   Excess struct member 'state_lock' description in 'efx_channel'
>   Excess struct member 'indir_table' description in 'efx_rss_context'
>   Excess struct member 'irq_rx_mod_step_us' description in 'efx_nic'
>   Excess struct member 'tx_queue' description in 'efx_nic'
>   Excess struct member 'rx_queue' description in 'efx_nic'
>   Excess struct member 'extra_channel_types' description in 'efx_nic'
>   expecting prototype for EFX_MAX_FRAME_LEN(). Prototype was for
>   EFX_FRAME_PAD() instead
> 
> along with "not described" warnings for the renamed members.
> 
> Fix the member names to match the structs, drop the entries for members
> that no longer exist, and move the EFX_FRAME_PAD define above the
> EFX_MAX_FRAME_LEN() comment, documenting its @mtu parameter.
> 
> No functional change.
> 
> Assisted-by: Claude:claude-opus-5-5
> Signed-off-by: Arnav Kapoor <kapoorarnav43@gmail.com>
> ---
> Comment-only change (plus moving a #define above the comment), checked
> with scripts/kernel-doc; W=1 build of drivers/net/ethernet/sfc/ shows no
> new warnings.
> 
>  drivers/net/ethernet/sfc/net_driver.h | 16 +++++++---------
>  1 file changed, 7 insertions(+), 9 deletions(-)
> 
> diff --git a/drivers/net/ethernet/sfc/net_driver.h b/drivers/net/ethernet/sfc/net_driver.h
> index 3964b2c56609..76b48f96ec62 100644
> --- a/drivers/net/ethernet/sfc/net_driver.h
> +++ b/drivers/net/ethernet/sfc/net_driver.h
> @@ -467,8 +467,6 @@ enum efx_sync_events_state {
>   * @irq_moderation_us: IRQ moderation value (in microseconds)
>   * @napi_dev: Net device used with NAPI
>   * @napi_str: NAPI control structure
> - * @state: state for NAPI vs busy polling
> - * @state_lock: lock protecting @state

Hi Arnav,

I agree that neither state nor state_lock exist in struct efx_channel.
But while checking that I noticed that it seems the documentation
for @busy_poll_state is missing.

Could you ask your AI friend to audit that aspect too?

>   * @eventq: Event queue buffer
>   * @eventq_mask: Event queue pointer mask
>   * @eventq_read_ptr: Event queue read pointer

...