| Message ID | 20240329-mac80211-kdoc-retval-v1-2-5e4d1ad6c250@quicinc.com (mailing list archive) |
|---|---|
| State | Awaiting Upstream |
| Delegated to: | Netdev Maintainers |
| Headers | show |
| Series | wifi: mac80211: Fix mac80211.h kernel-doc issues | expand |
On 3/29/24 13:27, Jeff Johnson wrote: > kernel-doc is reporting some warnings, so fix them: > > % scripts/kernel-doc -Wall -Werror -none include/net/mac80211.h > include/net/mac80211.h:2056: warning: No description found for return value of 'wdev_to_ieee80211_vif' > include/net/mac80211.h:2066: warning: No description found for return value of 'ieee80211_vif_to_wdev' > include/net/mac80211.h:5603: warning: No description found for return value of 'ieee80211_beacon_cntdwn_is_complete' > include/net/mac80211.h:5968: warning: No description found for return value of 'ieee80211_gtk_rekey_add' > include/net/mac80211.h:6350: warning: No description found for return value of 'ieee80211_find_sta_by_link_addrs' > include/net/mac80211.h:6478: warning: No description found for return value of 'ieee80211_txq_airtime_check' > include/net/mac80211.h:6981: warning: No description found for return value of 'rate_control_set_rates' > include/net/mac80211.h:7142: warning: No description found for return value of 'ieee80211_tx_prepare_skb' > include/net/mac80211.h:7156: warning: No description found for return value of 'ieee80211_parse_tx_radiotap' > include/net/mac80211.h:7277: warning: No description found for return value of 'ieee80211_tx_dequeue' > include/net/mac80211.h:7292: warning: No description found for return value of 'ieee80211_tx_dequeue_ni' > include/net/mac80211.h:7324: warning: No description found for return value of 'ieee80211_next_txq' > include/net/mac80211.h:7405: warning: No description found for return value of 'ieee80211_txq_may_transmit' > include/net/mac80211.h:7466: warning: No description found for return value of 'ieee80211_calc_rx_airtime' > include/net/mac80211.h:7480: warning: No description found for return value of 'ieee80211_calc_tx_airtime' > include/net/mac80211.h:7528: warning: No description found for return value of 'ieee80211_is_tx_data' > include/net/mac80211.h:7562: warning: No description found for return value of 'ieee80211_set_active_links' > 17 warnings as Errors > > Signed-off-by: Jeff Johnson <quic_jjohnson@quicinc.com> Acked-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Thanks. > --- > include/net/mac80211.h | 38 ++++++++++++++++++++++++++++++-------- > 1 file changed, 30 insertions(+), 8 deletions(-) > > diff --git a/include/net/mac80211.h b/include/net/mac80211.h > index e6a11a982ca8..8984ac4359b8 100644 > --- a/include/net/mac80211.h > +++ b/include/net/mac80211.h > @@ -2049,7 +2049,7 @@ static inline bool ieee80211_vif_is_mesh(struct ieee80211_vif *vif) > * This can be used by mac80211 drivers with direct cfg80211 APIs > * (like the vendor commands) that get a wdev. > * > - * Note that this function may return %NULL if the given wdev isn't > + * Return: pointer to the wdev, or %NULL if the given wdev isn't > * associated with a vif that the driver knows about (e.g. monitor > * or AP_VLAN interfaces.) > */ > @@ -2062,6 +2062,8 @@ struct ieee80211_vif *wdev_to_ieee80211_vif(struct wireless_dev *wdev); > * This can be used by mac80211 drivers with direct cfg80211 APIs > * (like the vendor commands) that needs to get the wdev for a vif. > * This can also be useful to get the netdev associated to a vif. > + * > + * Return: pointer to the wdev > */ > struct wireless_dev *ieee80211_vif_to_wdev(struct ieee80211_vif *vif); > > @@ -5597,7 +5599,7 @@ void ieee80211_csa_finish(struct ieee80211_vif *vif, unsigned int link_id); > * @vif: &struct ieee80211_vif pointer from the add_interface callback. > * @link_id: valid link_id during MLO or 0 for non-MLO > * > - * This function returns whether the countdown reached zero. > + * Return: %true if the countdown reached 1, %false otherwise > */ > bool ieee80211_beacon_cntdwn_is_complete(struct ieee80211_vif *vif, > unsigned int link_id); > @@ -5942,8 +5944,8 @@ void ieee80211_remove_key(struct ieee80211_key_conf *keyconf); > * key(s) will be available. These will be needed by mac80211 for proper > * RX processing, so this function allows setting them. > * > - * The function returns the newly allocated key structure, which will > - * have similar contents to the passed key configuration but point to > + * Return: the newly allocated key structure, which will have > + * similar contents to the passed key configuration but point to > * mac80211-owned memory. In case of errors, the function returns an > * ERR_PTR(), use IS_ERR() etc. > * > @@ -6342,6 +6344,8 @@ struct ieee80211_sta *ieee80211_find_sta_by_ifaddr(struct ieee80211_hw *hw, > * may be %NULL if the link ID is not needed > * > * Obtain the STA by link address, must use RCU protection. > + * > + * Return: pointer to STA if found, otherwise %NULL. > */ > struct ieee80211_sta * > ieee80211_find_sta_by_link_addrs(struct ieee80211_hw *hw, > @@ -6471,8 +6475,8 @@ void ieee80211_sta_register_airtime(struct ieee80211_sta *pubsta, u8 tid, > * @hw: pointer obtained from ieee80211_alloc_hw() > * @txq: pointer obtained from station or virtual interface > * > - * Return true if the AQL's airtime limit has not been reached and the txq can > - * continue to send more packets to the device. Otherwise return false. > + * Return: %true if the AQL's airtime limit has not been reached and the txq can > + * continue to send more packets to the device. Otherwise return %false. > */ > bool > ieee80211_txq_airtime_check(struct ieee80211_hw *hw, struct ieee80211_txq *txq); > @@ -6975,6 +6979,8 @@ bool rate_usable_index_exists(struct ieee80211_supported_band *sband, > * @hw: pointer as obtained from ieee80211_alloc_hw() > * @pubsta: &struct ieee80211_sta pointer to the target destination. > * @rates: new tx rate set to be used for this station. > + * > + * Return: 0 on success. An error code otherwise. > */ > int rate_control_set_rates(struct ieee80211_hw *hw, > struct ieee80211_sta *pubsta, > @@ -7135,6 +7141,8 @@ void ieee80211_report_wowlan_wakeup(struct ieee80211_vif *vif, > * @band: the band to transmit on > * @sta: optional pointer to get the station to send the frame to > * > + * Return: %true if the skb was prepared, %false otherwise > + * > * Note: must be called under RCU lock > */ > bool ieee80211_tx_prepare_skb(struct ieee80211_hw *hw, > @@ -7151,6 +7159,8 @@ bool ieee80211_tx_prepare_skb(struct ieee80211_hw *hw, > * > * @skb: packet injected by userspace > * @dev: the &struct device of this 802.11 device > + * > + * Return: %true if the radiotap header was parsed, %false otherwise > */ > bool ieee80211_parse_tx_radiotap(struct sk_buff *skb, > struct net_device *dev); > @@ -7260,7 +7270,7 @@ void ieee80211_unreserve_tid(struct ieee80211_sta *sta, u8 tid); > * @txq: pointer obtained from station or virtual interface, or from > * ieee80211_next_txq() > * > - * Returns the skb if successful, %NULL if no frame was available. > + * Return: the skb if successful, %NULL if no frame was available. > * > * Note that this must be called in an rcu_read_lock() critical section, > * which can only be released after the SKB was handled. Some pointers in > @@ -7286,6 +7296,8 @@ struct sk_buff *ieee80211_tx_dequeue(struct ieee80211_hw *hw, > * @hw: pointer as obtained from ieee80211_alloc_hw() > * @txq: pointer obtained from station or virtual interface, or from > * ieee80211_next_txq() > + * > + * Return: the skb if successful, %NULL if no frame was available. > */ > static inline struct sk_buff *ieee80211_tx_dequeue_ni(struct ieee80211_hw *hw, > struct ieee80211_txq *txq) > @@ -7317,7 +7329,7 @@ void ieee80211_handle_wake_tx_queue(struct ieee80211_hw *hw, > * @hw: pointer as obtained from ieee80211_alloc_hw() > * @ac: AC number to return packets from. > * > - * Returns the next txq if successful, %NULL if no queue is eligible. If a txq > + * Return: the next txq if successful, %NULL if no queue is eligible. If a txq > * is returned, it should be returned with ieee80211_return_txq() after the > * driver has finished scheduling it. > */ > @@ -7400,6 +7412,8 @@ ieee80211_return_txq(struct ieee80211_hw *hw, struct ieee80211_txq *txq, > * > * @hw: pointer as obtained from ieee80211_alloc_hw() > * @txq: pointer obtained from station or virtual interface > + * > + * Return: %true if transmission is allowed, %false otherwise > */ > bool ieee80211_txq_may_transmit(struct ieee80211_hw *hw, > struct ieee80211_txq *txq); > @@ -7460,6 +7474,8 @@ void ieee80211_nan_func_match(struct ieee80211_vif *vif, > * @status: &struct ieee80211_rx_status containing the transmission rate > * information. > * @len: frame length in bytes > + * > + * Return: the airtime estimate > */ > u32 ieee80211_calc_rx_airtime(struct ieee80211_hw *hw, > struct ieee80211_rx_status *status, > @@ -7474,6 +7490,8 @@ u32 ieee80211_calc_rx_airtime(struct ieee80211_hw *hw, > * @hw: pointer as obtained from ieee80211_alloc_hw() > * @info: &struct ieee80211_tx_info of the frame. > * @len: frame length in bytes > + * > + * Return: the airtime estimate > */ > u32 ieee80211_calc_tx_airtime(struct ieee80211_hw *hw, > struct ieee80211_tx_info *info, > @@ -7523,6 +7541,8 @@ ieee80211_obss_color_collision_notify(struct ieee80211_vif *vif, > * hardware encapsulation enabled are data frames. > * > * @skb: the frame to be transmitted. > + * > + * Return: %true if @skb is a data frame, %false otherwise > */ > static inline bool ieee80211_is_tx_data(struct sk_buff *skb) > { > @@ -7558,6 +7578,8 @@ static inline bool ieee80211_is_tx_data(struct sk_buff *skb) > * - change_sta_links(0x10) for each affected STA (the AP) > * - assign_vif_chanctx(link_id=4) > * - change_vif_links(0x10) > + * > + * Return: 0 on success. An error code otherwise. > */ > int ieee80211_set_active_links(struct ieee80211_vif *vif, u16 active_links); > >
diff --git a/include/net/mac80211.h b/include/net/mac80211.h index e6a11a982ca8..8984ac4359b8 100644 --- a/include/net/mac80211.h +++ b/include/net/mac80211.h @@ -2049,7 +2049,7 @@ static inline bool ieee80211_vif_is_mesh(struct ieee80211_vif *vif) * This can be used by mac80211 drivers with direct cfg80211 APIs * (like the vendor commands) that get a wdev. * - * Note that this function may return %NULL if the given wdev isn't + * Return: pointer to the wdev, or %NULL if the given wdev isn't * associated with a vif that the driver knows about (e.g. monitor * or AP_VLAN interfaces.) */ @@ -2062,6 +2062,8 @@ struct ieee80211_vif *wdev_to_ieee80211_vif(struct wireless_dev *wdev); * This can be used by mac80211 drivers with direct cfg80211 APIs * (like the vendor commands) that needs to get the wdev for a vif. * This can also be useful to get the netdev associated to a vif. + * + * Return: pointer to the wdev */ struct wireless_dev *ieee80211_vif_to_wdev(struct ieee80211_vif *vif); @@ -5597,7 +5599,7 @@ void ieee80211_csa_finish(struct ieee80211_vif *vif, unsigned int link_id); * @vif: &struct ieee80211_vif pointer from the add_interface callback. * @link_id: valid link_id during MLO or 0 for non-MLO * - * This function returns whether the countdown reached zero. + * Return: %true if the countdown reached 1, %false otherwise */ bool ieee80211_beacon_cntdwn_is_complete(struct ieee80211_vif *vif, unsigned int link_id); @@ -5942,8 +5944,8 @@ void ieee80211_remove_key(struct ieee80211_key_conf *keyconf); * key(s) will be available. These will be needed by mac80211 for proper * RX processing, so this function allows setting them. * - * The function returns the newly allocated key structure, which will - * have similar contents to the passed key configuration but point to + * Return: the newly allocated key structure, which will have + * similar contents to the passed key configuration but point to * mac80211-owned memory. In case of errors, the function returns an * ERR_PTR(), use IS_ERR() etc. * @@ -6342,6 +6344,8 @@ struct ieee80211_sta *ieee80211_find_sta_by_ifaddr(struct ieee80211_hw *hw, * may be %NULL if the link ID is not needed * * Obtain the STA by link address, must use RCU protection. + * + * Return: pointer to STA if found, otherwise %NULL. */ struct ieee80211_sta * ieee80211_find_sta_by_link_addrs(struct ieee80211_hw *hw, @@ -6471,8 +6475,8 @@ void ieee80211_sta_register_airtime(struct ieee80211_sta *pubsta, u8 tid, * @hw: pointer obtained from ieee80211_alloc_hw() * @txq: pointer obtained from station or virtual interface * - * Return true if the AQL's airtime limit has not been reached and the txq can - * continue to send more packets to the device. Otherwise return false. + * Return: %true if the AQL's airtime limit has not been reached and the txq can + * continue to send more packets to the device. Otherwise return %false. */ bool ieee80211_txq_airtime_check(struct ieee80211_hw *hw, struct ieee80211_txq *txq); @@ -6975,6 +6979,8 @@ bool rate_usable_index_exists(struct ieee80211_supported_band *sband, * @hw: pointer as obtained from ieee80211_alloc_hw() * @pubsta: &struct ieee80211_sta pointer to the target destination. * @rates: new tx rate set to be used for this station. + * + * Return: 0 on success. An error code otherwise. */ int rate_control_set_rates(struct ieee80211_hw *hw, struct ieee80211_sta *pubsta, @@ -7135,6 +7141,8 @@ void ieee80211_report_wowlan_wakeup(struct ieee80211_vif *vif, * @band: the band to transmit on * @sta: optional pointer to get the station to send the frame to * + * Return: %true if the skb was prepared, %false otherwise + * * Note: must be called under RCU lock */ bool ieee80211_tx_prepare_skb(struct ieee80211_hw *hw, @@ -7151,6 +7159,8 @@ bool ieee80211_tx_prepare_skb(struct ieee80211_hw *hw, * * @skb: packet injected by userspace * @dev: the &struct device of this 802.11 device + * + * Return: %true if the radiotap header was parsed, %false otherwise */ bool ieee80211_parse_tx_radiotap(struct sk_buff *skb, struct net_device *dev); @@ -7260,7 +7270,7 @@ void ieee80211_unreserve_tid(struct ieee80211_sta *sta, u8 tid); * @txq: pointer obtained from station or virtual interface, or from * ieee80211_next_txq() * - * Returns the skb if successful, %NULL if no frame was available. + * Return: the skb if successful, %NULL if no frame was available. * * Note that this must be called in an rcu_read_lock() critical section, * which can only be released after the SKB was handled. Some pointers in @@ -7286,6 +7296,8 @@ struct sk_buff *ieee80211_tx_dequeue(struct ieee80211_hw *hw, * @hw: pointer as obtained from ieee80211_alloc_hw() * @txq: pointer obtained from station or virtual interface, or from * ieee80211_next_txq() + * + * Return: the skb if successful, %NULL if no frame was available. */ static inline struct sk_buff *ieee80211_tx_dequeue_ni(struct ieee80211_hw *hw, struct ieee80211_txq *txq) @@ -7317,7 +7329,7 @@ void ieee80211_handle_wake_tx_queue(struct ieee80211_hw *hw, * @hw: pointer as obtained from ieee80211_alloc_hw() * @ac: AC number to return packets from. * - * Returns the next txq if successful, %NULL if no queue is eligible. If a txq + * Return: the next txq if successful, %NULL if no queue is eligible. If a txq * is returned, it should be returned with ieee80211_return_txq() after the * driver has finished scheduling it. */ @@ -7400,6 +7412,8 @@ ieee80211_return_txq(struct ieee80211_hw *hw, struct ieee80211_txq *txq, * * @hw: pointer as obtained from ieee80211_alloc_hw() * @txq: pointer obtained from station or virtual interface + * + * Return: %true if transmission is allowed, %false otherwise */ bool ieee80211_txq_may_transmit(struct ieee80211_hw *hw, struct ieee80211_txq *txq); @@ -7460,6 +7474,8 @@ void ieee80211_nan_func_match(struct ieee80211_vif *vif, * @status: &struct ieee80211_rx_status containing the transmission rate * information. * @len: frame length in bytes + * + * Return: the airtime estimate */ u32 ieee80211_calc_rx_airtime(struct ieee80211_hw *hw, struct ieee80211_rx_status *status, @@ -7474,6 +7490,8 @@ u32 ieee80211_calc_rx_airtime(struct ieee80211_hw *hw, * @hw: pointer as obtained from ieee80211_alloc_hw() * @info: &struct ieee80211_tx_info of the frame. * @len: frame length in bytes + * + * Return: the airtime estimate */ u32 ieee80211_calc_tx_airtime(struct ieee80211_hw *hw, struct ieee80211_tx_info *info, @@ -7523,6 +7541,8 @@ ieee80211_obss_color_collision_notify(struct ieee80211_vif *vif, * hardware encapsulation enabled are data frames. * * @skb: the frame to be transmitted. + * + * Return: %true if @skb is a data frame, %false otherwise */ static inline bool ieee80211_is_tx_data(struct sk_buff *skb) { @@ -7558,6 +7578,8 @@ static inline bool ieee80211_is_tx_data(struct sk_buff *skb) * - change_sta_links(0x10) for each affected STA (the AP) * - assign_vif_chanctx(link_id=4) * - change_vif_links(0x10) + * + * Return: 0 on success. An error code otherwise. */ int ieee80211_set_active_links(struct ieee80211_vif *vif, u16 active_links);
kernel-doc is reporting some warnings, so fix them: % scripts/kernel-doc -Wall -Werror -none include/net/mac80211.h include/net/mac80211.h:2056: warning: No description found for return value of 'wdev_to_ieee80211_vif' include/net/mac80211.h:2066: warning: No description found for return value of 'ieee80211_vif_to_wdev' include/net/mac80211.h:5603: warning: No description found for return value of 'ieee80211_beacon_cntdwn_is_complete' include/net/mac80211.h:5968: warning: No description found for return value of 'ieee80211_gtk_rekey_add' include/net/mac80211.h:6350: warning: No description found for return value of 'ieee80211_find_sta_by_link_addrs' include/net/mac80211.h:6478: warning: No description found for return value of 'ieee80211_txq_airtime_check' include/net/mac80211.h:6981: warning: No description found for return value of 'rate_control_set_rates' include/net/mac80211.h:7142: warning: No description found for return value of 'ieee80211_tx_prepare_skb' include/net/mac80211.h:7156: warning: No description found for return value of 'ieee80211_parse_tx_radiotap' include/net/mac80211.h:7277: warning: No description found for return value of 'ieee80211_tx_dequeue' include/net/mac80211.h:7292: warning: No description found for return value of 'ieee80211_tx_dequeue_ni' include/net/mac80211.h:7324: warning: No description found for return value of 'ieee80211_next_txq' include/net/mac80211.h:7405: warning: No description found for return value of 'ieee80211_txq_may_transmit' include/net/mac80211.h:7466: warning: No description found for return value of 'ieee80211_calc_rx_airtime' include/net/mac80211.h:7480: warning: No description found for return value of 'ieee80211_calc_tx_airtime' include/net/mac80211.h:7528: warning: No description found for return value of 'ieee80211_is_tx_data' include/net/mac80211.h:7562: warning: No description found for return value of 'ieee80211_set_active_links' 17 warnings as Errors Signed-off-by: Jeff Johnson <quic_jjohnson@quicinc.com> --- include/net/mac80211.h | 38 ++++++++++++++++++++++++++++++-------- 1 file changed, 30 insertions(+), 8 deletions(-)