Received-SPF: pass (google.com: domain of linux-kernel+bounces-158250-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:45e3:2400::1 as permitted sender) client-ip=2604:1380:45e3:2400::1;
Message-ID: <359adccd-adfe-4b48-893d-bc49a5977c81@intel.com>
Date: Thu, 25 Apr 2024 11:13:07 +0200
User-Agent: Mozilla Thunderbird
Subject: Re: [PATCH] kernel-doc: fix struct_group_tagged() parsing
To: Jonathan Corbet <corbet@lwn.net>
CC: Kees Cook <keescook@chromium.org>, Jakub Kicinski <kuba@kernel.org>, "Dan
 Williams" <dan.j.williams@intel.com>, "Gustavo A. R. Silva"
	<gustavoars@kernel.org>, Keith Packard <keithp@keithp.com>,
	<nex.sw.ncis.osdt.itp.upstreaming@intel.com>, <linux-doc@vger.kernel.org>,
	<netdev@vger.kernel.org>, <linux-kernel@vger.kernel.org>
References: <20240411093208.2483580-1-aleksander.lobakin@intel.com>
 <87r0eusgl9.fsf@meer.lwn.net>
From: Alexander Lobakin <aleksander.lobakin@intel.com>
Content-Language: en-US
In-Reply-To: <87r0eusgl9.fsf@meer.lwn.net>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: 7bit
Precedence: bulk
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?cXVhaWpmRHBoVUlQM0UzcXVYeStRcW5qTm5aK1lFcS9hbXFWS203OGRoY00z?=
 =?utf-8?B?RmlwRVc5ZERSMS8yMnFoVEVNUi9QQ3BxTmZaQjZXVko3QkNXRWRBdE1vMmlR?=
 =?utf-8?B?aTRlVXBXNmJmWmN2SW9tSEJXVUFIeDJoZU04T1V4aU9SOUN2VWFNWXlJcjBp?=
 =?utf-8?B?djFMaDBjZGh0T1Brc1o0bnFaSy9PTUMwTTZyRHlvcmVqcWZIRWFaMTVmZzRB?=
 =?utf-8?B?Z3JrU0g4R0hGNys4NkNnejhoSXhaZE9neFdSdFR4WHZieC9DMzBnM3J4cWZJ?=
 =?utf-8?B?eXZrNlIxelN3SGFhdEdVZk9yT0E0TXJTMHUwcDF0U2xoTEh2WHRtVWQvRDdT?=
 =?utf-8?B?WGJMWVFqMzZSRjlZUDVmL2R0TVA5RmN3bEZzK1k3WHkycmppRzVrMWVnK0t3?=
 =?utf-8?B?V1lXeDRWTzhEOW93WVZlMVdkeUpGUDYyRHpEREtYZ0YrMFhjU3RhUVNkQ3Bt?=
 =?utf-8?B?NUlzRVc1aExmalNWZ1MvQ2FoZzVYZ1krU3pRV1pFM1lKZHZoTEVlMW11V3dq?=
 =?utf-8?B?aEhUakZPRnVxcjhGOVFyVDQ5NTdCVDArdXRvd05MYTBhb2IwRmpxLzlFU2Nx?=
 =?utf-8?B?NXBTUkJQQzRhNGEvZEIwYWVjejdqUW5LM3ZEVXE2UElFUDBmN3UzNnlKNTBY?=
 =?utf-8?B?anRlSWZPV3pRK1BDczhkMzBJaEYzWHFjWVIwWWpqNUhiRk84UmpiSGF2bGdy?=
 =?utf-8?B?amNUcHRsS05IcGsvK2FHVm5yejJ1amcwblU0OEp2a1p0aGtWOU9NVml6WUF2?=
 =?utf-8?B?YUVWYVUyenRZTDVwK0w4cHI5U3RoRCtOSjRHdXgzaG1VY1hXOVJ4NjV0Yzhn?=
 =?utf-8?B?ZzhMQXRaK1RSOExZRzk5NmNoSzBUL1pHYk1ZMGFBVGhVdndpaEo5aGJ3bzZm?=
 =?utf-8?B?TWtmWE9hTGJPSmlnRjJaT1NNRG8vSGdlLzRNNms3N0ZPdnFmb0xKUzgzb09Q?=
 =?utf-8?B?YTZOTHgwV3I3a1EzL3hpVjZnQkF5UkJqWFdQR1BhelRkbmZQNzRndDZwOEVj?=
 =?utf-8?B?YWZXYUFKbndVUGdkMzU0ME4yTjRTSEprVWxpTUZhaXFoVnZ3SkNUWU1LRldj?=
 =?utf-8?B?NkVaMFcxaEVQSnBnNGZ3NkwxRlV1OW5uVVhmL0FheUJvZUp6eGNKVnd2d0JL?=
 =?utf-8?B?SmZiZW5yWk0rZ0tScWRtL0V5bEZEeVpFWGNwVFN1Q09qVVM5OHdGZzRYMVRo?=
 =?utf-8?B?R0NTQVVSYmlvVHdYZHQrWkFualF3SFlqcjJGV1g1M3dVUzMyNmtMVEtqY1BT?=
 =?utf-8?B?THlXbjJmSFhYSUdoYXBaTkhoOEgzUU5ZRGtrSnQvRTBHR3ZDZ2hhSG83eWlz?=
 =?utf-8?B?ZVRtUnZRZVhrZVZGWDNvanRrTm96a3B4Rkk3WVE4eUt6MURuK0RjYlo4emt3?=
 =?utf-8?B?ZmI1QnFBZVdQbm5uZDBVbnVnSVNNVDltNm56TmVpWWpyVktHVi9xcXVvUHF6?=
 =?utf-8?B?OEdhQStwQXoyOVY5RG1vdHErTGpsQWJuR1VkallxUk8zWDBIVjdFMVRnN21Y?=
 =?utf-8?B?Y3pIeHpCOTdJN1pkRStwUjJZanQySndUdXpUVmx5TEtPbWY5K3l6a3FMemNa?=
 =?utf-8?B?bm9PazV6VzhPVHZFb2xnNW5UTlpWVDN5YXV4TDBTNWQ1V1lhWFNvVVQyTGdR?=
 =?utf-8?B?ODVGcHZRakVYaDdGMVJhSGtjTlpmTUtMN2l5NXFPV1dsYk9iRElXQnIrejdt?=
 =?utf-8?B?VHU2Y0h1YkVXUGw0S29yOG15ZlZVLzJOeVV6VEpKNmpaY3VyMy9DTVZ6anNL?=
 =?utf-8?B?d1VjME5LOExNcnc3aGJuaUN2amtENDUyZ2syL3VXR1BPSlgxc2MvNDhPdW1R?=
 =?utf-8?B?N2tUSjF2MEJnaW9TMTlnNUo1TE5uWGtSMXJFcWZNTkVMOEVUNEkvcWlKWGFo?=
 =?utf-8?B?UTJ0cXNBckJaUTU0ZWUwSmtiZ1k4dWJFUFdhckJMYzhiaTVlMFR6OXE2YUMz?=
 =?utf-8?B?dWZQSmgrRmEwOXYvSjlPL0I5VkdCRFZtU1NkVW1ZMXg5UW50c0c4Z3JhQ2E0?=
 =?utf-8?B?SHIvemtORHprSmF0RVBMbm5CSHF4anMwYlJtWkN5TXllUU4yek53WnFSRUl3?=
 =?utf-8?B?Nk14K3A3aUV5T1RHeXlGQ2tiaXViREhSd0lrTVJMNmRkMmVXQWR1cU9Jb1cx?=
 =?utf-8?B?c2JoRW1ET3N5Zm5jTE1scjR0M05YNHNlS3owZmxoNlVpNHBiRUxobzR4YXda?=
 =?utf-8?B?dEE9PQ==?=
X-MS-Exchange-CrossTenant-Network-Message-Id: 23443dd4-a2f7-491b-92c6-08dc6507ee29
X-MS-Exchange-CrossTenant-AuthSource: DS0PR11MB8718.namprd11.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 25 Apr 2024 09:13:11.5638
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 46c98d88-e344-4ed4-8496-4ed7712e255d
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: BB9XH+do6Cgq2YwqC0w2IHFLGFZSwxOv8KiNLXNpBdQ31R8K2dRVswnwPUlVrnK4T10sxna/oilVmHd0nVqllMyC4zKO72cq/DdVvbmfkc0=
X-MS-Exchange-Transport-CrossTenantHeadersStamped: IA1PR11MB6292
X-OriginatorOrg: intel.com

From: Jonathan Corbet <corbet@lwn.net>
Date: Wed, 24 Apr 2024 13:31:14 -0600

> Alexander Lobakin <aleksander.lobakin@intel.com> writes:
> 
>> From: Kees Cook <keescook@chromium.org>
>>
>> kernel-doc emits a warning on struct_group_tagged() if you describe your
>> struct group member:
>>
>> include/net/libeth/rx.h:69: warning: Excess struct member 'fp' description in 'libeth_fq'
>>
>> The code:
>>
>> /**
>>  * struct libeth_fq - structure representing a buffer queue
>>  * @fp: hotpath part of the structure
>>  * @pp: &page_pool for buffer management
>> [...]
>>  */
>> struct libeth_fq {
>> 	struct_group_tagged(libeth_fq_fp, fp,
>> 		struct page_pool	*pp;
>> [...]
>> 	);
>>
>> When a struct_group_tagged() is encountered, we need to build a
>> `struct TAG NAME;` from it, so that it will be treated as a valid
>> embedded struct.
>> Decouple the regex and do the replacement there. As far as I can see,
>> this doesn't produce any new warnings on the current mainline tree.
>>
>> Reported-by: Jakub Kicinski <kuba@kernel.org>
>> Closes: https://lore.kernel.org/netdev/20240405212513.0d189968@kernel.org
>> Fixes: 50d7bd38c3aa ("stddef: Introduce struct_group() helper macro")
>> Signed-off-by: Kees Cook <keescook@chromium.org>
>> Co-developed-by: Alexander Lobakin <aleksander.lobakin@intel.com>
>> Signed-off-by: Alexander Lobakin <aleksander.lobakin@intel.com>
>> ---
>>  scripts/kernel-doc | 3 ++-
>>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> So, in docs-next, applying this *adds* two warnings:
> 
>> ./include/net/page_pool/types.h:77: warning: Function parameter or struct member 'fast' not described in 'page_pool_params'
>> ./include/net/page_pool/types.h:77: warning: Function parameter or struct member 'slow' not described in 'page_pool_params'
> 
> In truth, the warnings look correct.  I guess I'll leave this applied,
> but perhaps a fix for the warnings should go into the net tree?

Sure, we'll fix this. Thanks!

> 
> Thanks,
> 
> jon

Olek