Em Thu, 29 Mar 2018 11:47:07 +0200
Johannes Berg <johannes@xxxxxxxxxxxxxxxx> escreveu:
> 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
The original patchset for nested structs was supporting it only
when not inlined. This should be fixed on this patchset:
https://lkml.org/lkml/2018/2/19/387
Do you have those patches on your tree?
With regards to duplicated warnings, that use to happen if the same header
is included several times (with is a common pratice at the net subsystem).
I also submitted some patches to linux-next addressing it.
Could you please merge from docs-next and see if those problems
get solved?
It is located at:
git://git.lwn.net/linux.git docs-next
Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
