Received-SPF: pass (google.com: domain of linux-wireless+bounces-1057-linux.lists.archive=gmail.com@vger.kernel.org designates 147.75.80.249 as permitted sender) client-ip=147.75.80.249;
Message-ID: <5e0e5d84-3891-47a1-bce1-beb26cd19b7b@infradead.org>
Date: Tue, 19 Dec 2023 18:29:35 -0800
Precedence: bulk
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Subject: Re: [PATCH] wifi: cfg80211: address several kerneldoc warnings
Content-Language: en-US
To: Jeff Johnson <quic_jjohnson@quicinc.com>, Jonathan Corbet
 <corbet@lwn.net>, Johannes Berg <johannes@sipsolutions.net>
Cc: linux-wireless@vger.kernel.org, netdev@vger.kernel.org,
 linux-kernel@vger.kernel.org
References: <87plz1g2sc.fsf@meer.lwn.net>
 <56d7f97e-bc8b-465f-9e59-80028ccec995@quicinc.com>
From: Randy Dunlap <rdunlap@infradead.org>
In-Reply-To: <56d7f97e-bc8b-465f-9e59-80028ccec995@quicinc.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit


On 12/19/23 17:00, Jeff Johnson wrote:
> On 12/19/2023 4:01 PM, 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>
>> ---
>>  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
> 
> also missing the following?
>  * @links.addr: MLO per-link MAC address

Yes, that should also be fixed at some point.

What Jon is trying to do here is address a boatload of new kernel-doc warnings of the
"Excess struct member" variety.

> 
>> + * @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.
>>   */
> 
> 

Thanks.
-- 
#Randy
https://people.kernel.org/tglx/notes-about-netiquette
https://subspace.kernel.org/etiquette.html