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

[Austin, Alex (DCCG)]

On 07/10/2026 18:53, 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.
>
> kernel-doc -Wall also reports three members that are not described
> because nothing in the driver uses them any more, so remove them rather
> than document them:
>
>   - efx_channel::busy_poll_state, left behind when commit e7fe9491261e
>     ("sfc: get rid of custom busy polling code") removed its users.
>     @state and @state_lock above were its old kernel-doc entries.
>   - efx_tx_queue::flush_outstanding, only used by the Falcon/Siena
>     flush code, which commit 36ff6393292d ("sfc: Move Siena specific
>     files") moved into siena/ with its own copy of the struct.
>   - efx_rx_queue::min_overfill, whose kernel-doc entry and only
>     assignment were removed by commit ecc910f520ba ("sfc: Make the dmaq
>     size a run-time setting (rather than compile-time)").
>
> The warnings were found with scripts/kernel-doc -Wall. I don't have sfc
> hardware; this is compile-tested only.
>
> No functional change.
>
> Assisted-by: LLM
> Signed-off-by: Arnav Kapoor <kapoorarnav43@xxxxxxxxx>
> ---
> Changes in v2:
> - Remove busy_poll_state, flush_outstanding and min_overfill, which are
>   unused, instead of leaving them undocumented (Simon)
> - Use the Assisted-by format from coding-assistants.rst
>
> net_driver.h has further members with no kernel-doc description,
> mostly in struct efx_nic and struct efx_nic_type. Those are in use, so
> I'll document them in a separate patch.
>
> W=1 build of drivers/net/ethernet/sfc/ shows no new warnings.
>
> v1: https://lore.kernel.org/all/20261003055443.144554-1-kapoorarnav43@xxxxxxxxx/
>
>  drivers/net/ethernet/sfc/net_driver.h | 21 +++++++--------------
>  1 file changed, 7 insertions(+), 14 deletions(-)
>

Reviewed-by: Alex Austin <alex.austin@xxxxxxx>