From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.1 (2015-04-28) on archive.lwn.net X-Spam-Level: X-Spam-Status: No, score=-4.8 required=5.0 tests=HEADER_FROM_DIFFERENT_DOMAINS, RCVD_IN_DNSWL_HI,T_RP_MATCHES_RCVD autolearn=ham autolearn_force=no version=3.4.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by archive.lwn.net (Postfix) with ESMTP id 229817DD31 for ; Thu, 29 Mar 2018 14:22:23 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751167AbeC2OWW (ORCPT ); Thu, 29 Mar 2018 10:22:22 -0400 Received: from osg.samsung.com ([64.30.133.232]:56030 "EHLO osg.samsung.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751164AbeC2OWV (ORCPT ); Thu, 29 Mar 2018 10:22:21 -0400 Received: from localhost (localhost [127.0.0.1]) by osg.samsung.com (Postfix) with ESMTP id 5F8C43ED43; Thu, 29 Mar 2018 07:22:21 -0700 (PDT) X-Virus-Scanned: Debian amavisd-new at dev.s-opensource.com Received: from osg.samsung.com ([127.0.0.1]) by localhost (localhost [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id x4T1jKjHZpIf; Thu, 29 Mar 2018 07:22:15 -0700 (PDT) Received: from vento.lan (177.205.88.90.dynamic.adsl.gvt.net.br [177.205.88.90]) by osg.samsung.com (Postfix) with ESMTPSA id 6FCE03ED3B; Thu, 29 Mar 2018 07:22:13 -0700 (PDT) Date: Thu, 29 Mar 2018 11:22:09 -0300 From: Mauro Carvalho Chehab To: Johannes Berg Cc: linux-doc@vger.kernel.org, linux-wireless@vger.kernel.org Subject: Re: nested structs parsing Message-ID: <20180329112209.5c0e0320@vento.lan> In-Reply-To: <1522316827.5932.11.camel@sipsolutions.net> References: <1522316775.5932.10.camel@sipsolutions.net> <1522316827.5932.11.camel@sipsolutions.net> Organization: Samsung X-Mailer: Claws Mail 3.15.1-dirty (GTK+ 2.24.32; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Sender: linux-doc-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-doc@vger.kernel.org Em Thu, 29 Mar 2018 11:47:07 +0200 Johannes Berg 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@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html