On Thu, 2018-03-29 at 11:46 +0200, Johannes Berg wrote:
> Hi,
>
> For a while I haven't looked at my documentation for 802.11, and now I
> noticed I'm getting warnings due to the nested parsing.
>
> However, something seems to be wrong? I have, for example, this (in
> net/mac80211/sta_info.h)
>
> struct sta_info {
> ...
> struct {
> u64 packets[IEEE80211_NUM_ACS];
> u64 bytes[IEEE80211_NUM_ACS];
> struct ieee80211_tx_rate last_rate;
> u64 msdu[IEEE80211_NUM_TIDS + 1];
> } tx_stats;
> };
>
> but I'm getting the following warnings now, with only "@tx_stats" being
> described in the documentation:
>
> net/mac80211/sta_info.h:590: warning: Function parameter or member 'status_stats.last_ack' not described in 'sta_info'
> net/mac80211/sta_info.h:590: warning: Function parameter or member 'status_stats.last_ack_signal' not described in 'sta_info'
> net/mac80211/sta_info.h:590: warning: Function parameter or member 'status_stats.ack_signal_filled' not described in 'sta_info'
> net/mac80211/sta_info.h:590: warning: Function parameter or member 'msdu' not described in 'sta_info'
>
> I can understand the first three of those, but not the last one? Why is
> the last one not qualified?
>
> If I change it to this:
>
> struct {
> u64 packets[IEEE80211_NUM_ACS];
> u64 bytes[IEEE80211_NUM_ACS];
> /**
> * @last_rate: last TX rate
> */
> struct ieee80211_tx_rate last_rate;
> /**
> * @msdu: # of MSDUs per TID
> */
> u64 msdu[IEEE80211_NUM_TIDS + 1];
> } tx_stats;
>
> I still get a warning on "tx_stats.last_rate", but not on "msdu", which
> is sort of obvious from the warning text, but also rather unexpected.
>
> Normally I'd say that the "msdu" warning is originally wrong
>
> However, I'd also argue that if I'm using inline declarations, I
> shouldn't have to write it like this:
>
> struct {
> u64 packets[IEEE80211_NUM_ACS];
> u64 bytes[IEEE80211_NUM_ACS];
> /**
> * @tx_stats.last_rate: last TX rate
> */
> struct ieee80211_tx_rate last_rate;
> ...
> } tx_stats;
Whoops, sent a fraction of a second too early - this actually causes a
warning too (no idea why four times):
net/mac80211/sta_info.h:560: warning: Incorrect use of kernel-doc format: * @tx_stats.last_rate: last TX rate
net/mac80211/sta_info.h:560: warning: Incorrect use of kernel-doc format: * @tx_stats.last_rate: last TX rate
net/mac80211/sta_info.h:560: warning: Incorrect use of kernel-doc format: * @tx_stats.last_rate: last TX rate
net/mac80211/sta_info.h:560: warning: Incorrect use of kernel-doc format: * @tx_stats.last_rate: last TX rate
johannes
