wifi: cfg80211: address several kerneldoc warnings

include/net/cfg80211.h includes a number of kerneldoc entries for struct
members that do not exist, leading to these warnings:

  ./include/net/cfg80211.h:3192: warning: Excess struct member 'band_pref' description in 'cfg80211_bss_selection'
  ./include/net/cfg80211.h:3192: warning: Excess struct member 'adjust' description in 'cfg80211_bss_selection'
  ./include/net/cfg80211.h:6181: warning: Excess struct member 'bssid' description in 'wireless_dev'
  ./include/net/cfg80211.h:6181: warning: Excess struct member 'beacon_interval' description in 'wireless_dev'
  ./include/net/cfg80211.h:7299: warning: Excess struct member 'bss' description in 'cfg80211_rx_assoc_resp_data'

Remove and/or repair each entry to address the warnings and ensure a proper
docs build for the affected structures.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 include/net/cfg80211.h | 11 ++++-------
 1 file changed, 4 insertions(+), 7 deletions(-)

On 12/19/23 16:01, Jonathan Corbet wrote:
> include/net/cfg80211.h includes a number of kerneldoc entries for struct
> members that do not exist, leading to these warnings:
> 
>   ./include/net/cfg80211.h:3192: warning: Excess struct member 'band_pref' description in 'cfg80211_bss_selection'
>   ./include/net/cfg80211.h:3192: warning: Excess struct member 'adjust' description in 'cfg80211_bss_selection'
>   ./include/net/cfg80211.h:6181: warning: Excess struct member 'bssid' description in 'wireless_dev'
>   ./include/net/cfg80211.h:6181: warning: Excess struct member 'beacon_interval' description in 'wireless_dev'
>   ./include/net/cfg80211.h:7299: warning: Excess struct member 'bss' description in 'cfg80211_rx_assoc_resp_data'
> 
> Remove and/or repair each entry to address the warnings and ensure a proper
> docs build for the affected structures.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>


> ---
>  include/net/cfg80211.h | 11 ++++-------
>  1 file changed, 4 insertions(+), 7 deletions(-)
> 
> diff --git a/include/net/cfg80211.h b/include/net/cfg80211.h
> index b137a33a1b68..81c46c8e2a68 100644
> --- a/include/net/cfg80211.h
> +++ b/include/net/cfg80211.h
> @@ -3180,8 +3180,8 @@ struct cfg80211_ibss_params {
>   *
>   * @behaviour: requested BSS selection behaviour.
>   * @param: parameters for requestion behaviour.
> - * @band_pref: preferred band for %NL80211_BSS_SELECT_ATTR_BAND_PREF.
> - * @adjust: parameters for %NL80211_BSS_SELECT_ATTR_RSSI_ADJUST.
> + * @param.band_pref: preferred band for %NL80211_BSS_SELECT_ATTR_BAND_PREF.
> + * @param.adjust: parameters for %NL80211_BSS_SELECT_ATTR_RSSI_ADJUST.
>   */
>  struct cfg80211_bss_selection {
>  	enum nl80211_bss_select_attr behaviour;
> @@ -6013,7 +6013,6 @@ void wiphy_delayed_work_flush(struct wiphy *wiphy,
>   *	wireless device if it has no netdev
>   * @u: union containing data specific to @iftype
>   * @connected: indicates if connected or not (STA mode)
> - * @bssid: (private) Used by the internal configuration code
>   * @wext: (private) Used by the internal wireless extensions compat code
>   * @wext.ibss: (private) IBSS data part of wext handling
>   * @wext.connect: (private) connection handling data
> @@ -6033,8 +6032,6 @@ void wiphy_delayed_work_flush(struct wiphy *wiphy,
>   * @mgmt_registrations: list of registrations for management frames
>   * @mgmt_registrations_need_update: mgmt registrations were updated,
>   *	need to propagate the update to the driver
> - * @beacon_interval: beacon interval used on this device for transmitting
> - *	beacons, 0 when not valid
>   * @address: The address for this device, valid only if @netdev is %NULL
>   * @is_running: true if this is a non-netdev device that has been started, e.g.
>   *	the P2P Device.
> @@ -7270,8 +7267,6 @@ void cfg80211_auth_timeout(struct net_device *dev, const u8 *addr);
>  
>  /**
>   * struct cfg80211_rx_assoc_resp_data - association response data
> - * @bss: the BSS that association was requested with, ownership of the pointer
> - *	moves to cfg80211 in the call to cfg80211_rx_assoc_resp()
>   * @buf: (Re)Association Response frame (header + body)
>   * @len: length of the frame data
>   * @uapsd_queues: bitmap of queues configured for uapsd. Same format
> @@ -7281,6 +7276,8 @@ void cfg80211_auth_timeout(struct net_device *dev, const u8 *addr);
>   * @ap_mld_addr: AP MLD address (in case of MLO)
>   * @links: per-link information indexed by link ID, use links[0] for
>   *	non-MLO connections
> + * @links.bss: the BSS that association was requested with, ownership of the
> + *      pointer moves to cfg80211 in the call to cfg80211_rx_assoc_resp()
>   * @links.status: Set this (along with a BSS pointer) for links that
>   *	were rejected by the AP.
>   */

Jonathan Corbet <corbet@lwn.net> writes:

> include/net/cfg80211.h includes a number of kerneldoc entries for struct
> members that do not exist, leading to these warnings:
>
>   ./include/net/cfg80211.h:3192: warning: Excess struct member 'band_pref' description in 'cfg80211_bss_selection'
>   ./include/net/cfg80211.h:3192: warning: Excess struct member 'adjust' description in 'cfg80211_bss_selection'
>   ./include/net/cfg80211.h:6181: warning: Excess struct member 'bssid' description in 'wireless_dev'
>   ./include/net/cfg80211.h:6181: warning: Excess struct member 'beacon_interval' description in 'wireless_dev'
>   ./include/net/cfg80211.h:7299: warning: Excess struct member 'bss' description in 'cfg80211_rx_assoc_resp_data'
>
> Remove and/or repair each entry to address the warnings and ensure a proper
> docs build for the affected structures.
>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>

I try to periodically check for kerneldoc warnings in wireless trees but
I have never seen these. Am I missing something or did you do something
special (enable new warnings etc.)?

On 12/19/23 22:35, Kalle Valo wrote:
> Jonathan Corbet <corbet@lwn.net> writes:
> 
>> include/net/cfg80211.h includes a number of kerneldoc entries for struct
>> members that do not exist, leading to these warnings:
>>
>>   ./include/net/cfg80211.h:3192: warning: Excess struct member 'band_pref' description in 'cfg80211_bss_selection'
>>   ./include/net/cfg80211.h:3192: warning: Excess struct member 'adjust' description in 'cfg80211_bss_selection'
>>   ./include/net/cfg80211.h:6181: warning: Excess struct member 'bssid' description in 'wireless_dev'
>>   ./include/net/cfg80211.h:6181: warning: Excess struct member 'beacon_interval' description in 'wireless_dev'
>>   ./include/net/cfg80211.h:7299: warning: Excess struct member 'bss' description in 'cfg80211_rx_assoc_resp_data'
>>
>> Remove and/or repair each entry to address the warnings and ensure a proper
>> docs build for the affected structures.
>>
>> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> 
> I try to periodically check for kerneldoc warnings in wireless trees but
> I have never seen these. Am I missing something or did you do something
> special (enable new warnings etc.)?

There are new patches from both Kees Cook and me to report Excess kernel-doc
descriptions, so now there are a bunch of kernel-doc warnings that we are working
to fix quickly.  :(