[PATCH] cfg80211/mac80211: fix doc compilation warnings

[PATCH] cfg80211/mac80211: fix doc compilation warnings

[Michael Opdenacker]

This patch fixes countless "No description found for parameter"
warnings generating documentation (running "make htmldocs"),
because the comments do not match the actual prototypes in the code.

This issue didn't exist in 3.9. It may we worth fixing in 3.10
(if it's not too late).

Signed-off-by: Michael Opdenacker <michael.opdenacker@free-electrons.com>
---
 include/net/cfg80211.h | 1 +
 include/net/mac80211.h | 4 ++--
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/include/net/cfg80211.h b/include/net/cfg80211.h
index 26b5b69..3949642 100644
--- a/include/net/cfg80211.h
+++ b/include/net/cfg80211.h
@@ -4153,6 +4153,7 @@ void cfg80211_report_wowlan_wakeup(struct wireless_dev *wdev,
  * cfg80211_crit_proto_stopped() - indicate critical protocol stopped by driver.
  *
  * @wdev: the wireless device for which critical protocol is stopped.
+ * @gfp: the type of memory to allocate (see kmalloc).
  *
  * This function can be called by the driver to indicate it has reverted
  * operation back to normal. One reason could be that the duration given
diff --git a/include/net/mac80211.h b/include/net/mac80211.h
index 885898a..79f5fa7 100644
--- a/include/net/mac80211.h
+++ b/include/net/mac80211.h
@@ -1235,7 +1235,7 @@ enum ieee80211_sta_rx_bandwidth {
  * struct ieee80211_sta_rates - station rate selection table
  *
  * @rcu_head: RCU head used for freeing the table on update
- * @rates: transmit rates/flags to be used by default.
+ * @rate: transmit rates/flags to be used by default.
  *	Overriding entries per-packet is possible by using cb tx control.
  */
 struct ieee80211_sta_rates {
@@ -1276,7 +1276,7 @@ struct ieee80211_sta_rates {
  *	notifications and capabilities. The value is only valid after
  *	the station moves to associated state.
  * @smps_mode: current SMPS mode (off, static or dynamic)
- * @tx_rates: rate control selection table
+ * @rates: station rate selection table
  */
 struct ieee80211_sta {
 	u32 supp_rates[IEEE80211_NUM_BANDS];
-- 
1.8.1.2

Re: [PATCH] cfg80211/mac80211: fix doc compilation warnings

[Johannes Berg]

On Tue, 2013-06-25 at 21:48 +0200, Michael Opdenacker wrote:
> This patch fixes countless "No description found for parameter"
> warnings generating documentation (running "make htmldocs"),
> because the comments do not match the actual prototypes in the code.
> 
> This issue didn't exist in 3.9. It may we worth fixing in 3.10
> (if it's not too late).

I think it's way late. Besides, all of this is already fixed in -next
trees.


> @@ -4153,6 +4153,7 @@ void cfg80211_report_wowlan_wakeup(struct wireless_dev *wdev,
>   * cfg80211_crit_proto_stopped() - indicate critical protocol stopped by driver.
>   *
>   * @wdev: the wireless device for which critical protocol is stopped.
> + * @gfp: the type of memory to allocate (see kmalloc).

This is also wrong, the allocation flags don't really change the *type*
of memory, but only *how* it is allocated.

johannes

Re: [PATCH] cfg80211/mac80211: fix doc compilation warnings

[Michael Opdenacker]

Hi Johannes,

Thank you for your review!

On 06/26/2013 09:37 AM, Johannes Berg wrote:
> On Tue, 2013-06-25 at 21:48 +0200, Michael Opdenacker wrote:
>> This patch fixes countless "No description found for parameter"
>> warnings generating documentation (running "make htmldocs"),
>> because the comments do not match the actual prototypes in the code.
>>
>> This issue didn't exist in 3.9. It may we worth fixing in 3.10
>> (if it's not too late).
> I think it's way late. Besides, all of this is already fixed in -next
> trees.
Cool! That's good news :)
>
>
>> @@ -4153,6 +4153,7 @@ void cfg80211_report_wowlan_wakeup(struct wireless_dev *wdev,
>>   * cfg80211_crit_proto_stopped() - indicate critical protocol stopped by driver.
>>   *
>>   * @wdev: the wireless device for which critical protocol is stopped.
>> + * @gfp: the type of memory to allocate (see kmalloc).
> This is also wrong, the allocation flags don't really change the *type*
> of memory, but only *how* it is allocated.
I agree, but I chose to stick to the description I found 5 times in
include/linux/slab.h. I shouldn't have followed bad examples...

I'll submit another patch ;)

Thanks again,

Michael.

-- 
Michael Opdenacker, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com
+33 484 258 098