From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 949A23DF008; Wed, 16 Sep 2026 20:45:33 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=198.137.202.133 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1789591539; cv=none; b=fTgNYmJO38zC74Z6fgbIBn5ecMdHbuRMxrnJOkPNAK3cmMBBXHTqo8yq16G0fN2nsRxg7IQ9J5oigjD5ooR2NSw/ai0OMhXuTbg/cK1KI4xgCspkPoA2XokhUGrSYgPLZ6k3YQsK0+yaBB4a1tv/o/A5hh/OYoTYcjTan27Vkcc= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1789591539; c=relaxed/simple; bh=hjTvvy91IucTh3uvTAe8EJ5wySr8vMkmQuHDiStZ1Us=; h=Message-ID:Date:MIME-Version:Subject:To:Cc:References:From: In-Reply-To:Content-Type; b=dDSULc0ptbvin6rZt3HLHKL/db68amJiZtSiGB7og1yWD2IobuGtnh87VV0bdt19sO2RlLJJGBeNa/hEadBgiHqDhkxPgUidx+Ygha38n9GzpP1UXIGAStQJlLAY4CcXaihc13u1tqGigheNCO0xEJlAvPy3PFfg3AP2ni0PRx8= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=infradead.org; spf=pass smtp.mailfrom=infradead.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b=rwLIQ2+I; arc=none smtp.client-ip=198.137.202.133 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=infradead.org Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=infradead.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="rwLIQ2+I" DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20210309; h=Content-Transfer-Encoding: Content-Type:In-Reply-To:From:References:Cc:To:Subject:MIME-Version:Date: Message-ID:Sender:Reply-To:Content-ID:Content-Description; bh=0e4JuDoGwJko+bWyw7DMuKSr0o57ajEnpbZrPm7VLzw=; b=rwLIQ2+IvPMDeexyGSSoUIWAlW vcOYNsE8OHjcoqWBx3G+PcIAvTX6tINDBo5QnGL3H9kVNaUSyNgPP2eA/PLBegpel8aTh7Y+NrVIX CpZqNWonEnKVZBww4olulWDz/7pG0jL0WmTNMRv/DQr8dPbLbE0i88PFDx9UeBrmM1ujhj09ceSpF C30iw3gx+Kt+cBSN4Yp2DhyvPORqCBJf6feRFOPgSNyIMGCFkkoMYdrthFr2LaLA+3MmijQIxTWdz K11Almdt5ybXRn0OPjRKgl/OyJlX7O087zGXCKYkLOGtjk+3Lmz6N1cjsYzHkw2UO9+i/XU4fMloP up/CE/Jw==; Received: from [50.53.43.113] (helo=[192.168.254.34]) by bombadil.infradead.org with esmtpsa (Exim 4.99.1 #2 (Red Hat Linux)) id 1x6wVV-0000000A5dA-3pSq; Wed, 16 Sep 2026 20:45:29 +0000 Message-ID: Date: Wed, 16 Sep 2026 13:45:29 -0700 Precedence: bulk X-Mailing-List: linux-doc@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: Re: [PATCH] docs: kdoc: fix struct_group_tagged() parsing regression To: Omokefe Emmanuel Onanaroghene , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, netdev@vger.kernel.org, intel-wired-lan@lists.osuosl.org Cc: corbet@lwn.net, skhan@linuxfoundation.org, mchehab@kernel.org, aleksander.lobakin@intel.com, aleksandr.loktionov@intel.com, tudor.ambarus@linaro.org, bvanassche@acm.org References: <20260914155127.21515-1-emmaonana18@gmail.com> Content-Language: en-US From: Randy Dunlap In-Reply-To: <20260914155127.21515-1-emmaonana18@gmail.com> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit Hi-- On 9/14/26 8:51 AM, Omokefe Emmanuel Onanaroghene wrote: > kernel-doc reports struct_group_tagged() members as excess because > the macro transformation rewrites it to an anonymous struct and drops their > member names. > > Keep the tag and member name when transforming struct_group_tagged(). The > nested members are then recorded as names such as fast.order; accept the > existing unqualified @order documentation tag during validation. > > Add a regression test based on struct page_pool_params. > > Reported-by: Randy Dunlap > Link: https://lore.kernel.org/all/0cf8ea5f-418f-45f0-907c-3d1ed4f03e9f@infradead.org/ > Fixes: 2f07ddbd5793 ("docs: xforms_lists: better evaluate struct_group macros") > Signed-off-by: Omokefe Emmanuel Onanaroghene > --- > tools/lib/python/kdoc/kdoc_parser.py | 4 ++- > tools/lib/python/kdoc/xforms_lists.py | 2 +- > tools/unittests/test_kdoc_parser.py | 37 +++++++++++++++++++++++++++ > 3 files changed, 41 insertions(+), 2 deletions(-) > > diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py > index d9ad1ddc87dd..ced09504f3d7 100644 > --- a/tools/lib/python/kdoc/kdoc_parser.py > +++ b/tools/lib/python/kdoc/kdoc_parser.py > @@ -635,7 +635,9 @@ class KernelDoc: > continue > if param_name.startswith("{unnamed_"): > continue > - if param_name in self.entry.parameterlist: > + if param_name in self.entry.parameterlist or \ > + any(actual.endswith('.' + param_name) > + for actual in self.entry.parameterlist): > continue > > hint = self.get_suggestions_hint(param_name, self.entry.parameterlist) > diff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/xforms_lists.py > index e3dda2fe8a53..9e8b3a6b1da1 100644 > --- a/tools/lib/python/kdoc/xforms_lists.py > +++ b/tools/lib/python/kdoc/xforms_lists.py > @@ -60,7 +60,7 @@ class CTransforms: > # > (CMatch("struct_group"), r"struct { \2+ };"), > (CMatch("struct_group_attr"), r"struct { \3+ };"), > - (CMatch("struct_group_tagged"), r"struct { \3+ };"), > + (CMatch("struct_group_tagged"), r"struct \1 { \3+ } \2;"), > (CMatch("__struct_group"), r"struct { \4+ };"), > ] > > diff --git a/tools/unittests/test_kdoc_parser.py b/tools/unittests/test_kdoc_parser.py > index c4a76ed13dbc..1a8287e99f2e 100755 > --- a/tools/unittests/test_kdoc_parser.py > +++ b/tools/unittests/test_kdoc_parser.py > @@ -418,6 +418,43 @@ class TestSelfValidate(GenerateKdocItem): > """ > self.run_test(self.SOURCE, [self.DEFAULT.copy()], self.EXPORTS) > > + > +class TestStructGroupTagged(GenerateKdocItem): > + def test_nested_struct_group_tagged_members(self): > + source = """ > + /** > + * struct page_pool_params - page pool parameters > + * @fast: Fast path parameters. > + * @order: Order of pages. > + * @pool_size: Number of pages. > + * @slow: Slow path parameters. > + * @netdev: Net device pointer. > + * @queue_idx: Queue index. > + * @flags: Flags. > + */ > + struct page_pool_params { > + struct_group_tagged(page_pool_params_fast, fast, > + unsigned int order; > + unsigned int pool_size; > + ); > + struct_group_tagged(page_pool_params_slow, slow, > + struct net_device *netdev; > + unsigned int queue_idx; > + unsigned int flags; > + ); > + }; > + """ > + > + kernel_doc = KernelDoc(self.config, "test.c", self.xforms) > + patcher = patch('builtins.open', new_callable=mock_open, > + read_data=dedent(source)) > + with patcher: > + _, entries = kernel_doc.parse_kdoc() > + > + self.assertEqual(len(entries), 1) > + self.assertEqual(entries[0].warnings, []) > + > + > # > # Class and logic to create dynamic tests from YAML > # Would something similar to this work for this warning? Warning: include/linux/debugfs.h:246 context_lock_struct(debugfs_cancellation) { struct list_head list; void (*cancel)(struct dentry *, void *); void *cancel_data; }; error: Cannot parse struct or union! Even though context_lock_struct is in xforms_list.py, it's not working in this case (above). thanks. -- ~Randy