From nobody Sat Oct 4 15:57:31 2025 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (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 9630723ABBE; Thu, 14 Aug 2025 15:40:46 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755186048; cv=none; b=bwx+9oDYwgfdHgTwj9GyCGR9U3fiYVj6lU403z7ETk997/0GNHMLvkB0F9SRDefWmDkGbqsPRiVHNA+L1IyQCH8+CbBLUovRQY9KQch2PlfJ0OCNyf6qtLCj+RSpWX7QZHPBYFXplISyTcumpblzar249FN6GR+6clNGN+v77Bo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755186048; c=relaxed/simple; bh=V9vBaVYsGOM89/AbSRckdlw4a3N2Szaq0f/Y7+Wrt9Y=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=CQOz8GG8eEQDW368ymBmqKDQCxgoU4PzWFzXNspnkG0SDKW2wIY0z/Ynb6jLMx7euMsSwcfyNq/DFJmW2MDbH7di9hReJF4okvVe2hgO+1v69rfsHjZj21SRG3UrLEH2mmSY78+tXMt3GXqKk3B2fg+8jBneYdHjdxnB4p+Vxnk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=kHDEHFX8; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="kHDEHFX8" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 9EBC240AF4 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1755186046; bh=u5Ei5e6Ezbbc3DM6w/yyx0CojNL/+K85VRUr7EDaWpk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=kHDEHFX8Qzxw4WOU+LRLSdMENlNye8XgdlNu3KqeACjmCWl4GqrHtAOTt5bn1JFmx QoRgQhF/K91ws4efH3BuWw5FdzQjZjBHejvUIWCsZRn/op7lAzSuu2HkuchWtqPDOg LNDBDAQMguTKew9lzPA2Hb+5df5nRw7qqIO93WNAB7czoc5POIeUB9X13a6U5I8Wcm AqNR/LxIXFMqJQVAv6Bi1ZJPxAhU+ZN/CGJ/r42w7j6Lcic18pWpmlMjttGR276fQz SHmPxwtpwm6lyhKnJDOGC7qrhrtPblm09SxxqlkEhAlIyBFhCS7/B/u2iHemBaIynj /R1eQeNp8hFLQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 9EBC240AF4; Thu, 14 Aug 2025 15:40:45 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH v2 1/7] docs: kdoc: remove dead code Date: Thu, 14 Aug 2025 09:40:29 -0600 Message-ID: <20250814154035.328769-2-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250814154035.328769-1-corbet@lwn.net> References: <20250814154035.328769-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" create_parameter_list() tests an argument against the same regex twice, in two different locations; remove the pointless extra tests and the never-executed error cases that go with them. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 22 ++++++---------------- 1 file changed, 6 insertions(+), 16 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 9e65948f8254..96e3fe4ec431 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -564,28 +564,18 @@ class KernelDoc: args.insert(0, first_arg.pop()) dtype =3D ' '.join(first_arg) =20 + bitfield_re =3D KernRe(r'(.*?):(\w+)') for param in args: - if KernRe(r'^(\*+)\s*(.*)').match(param): - r =3D KernRe(r'^(\*+)\s*(.*)') - if not r.match(param): - self.emit_msg(ln, f"Invalid param: {param}") - continue - - param =3D r.group(1) - + r =3D KernRe(r'^(\*+)\s*(.*)') + if r.match(param): self.push_parameter(ln, decl_type, r.group(2), f"{dtype} {r.group(1)}", arg, declaration_name) =20 - elif KernRe(r'(.*?):(\w+)').search(param): - r =3D KernRe(r'(.*?):(\w+)') - if not r.match(param): - self.emit_msg(ln, f"Invalid param: {param}") - continue - + elif bitfield_re.search(param): if dtype !=3D "": # Skip unnamed bit-fields - self.push_parameter(ln, decl_type, r.group(1), - f"{dtype}:{r.group(2)}", + self.push_parameter(ln, decl_type, bitfield_re= .group(1), + f"{dtype}:{bitfield_re.gro= up(2)}", arg, declaration_name) else: self.push_parameter(ln, decl_type, param, dtype, --=20 2.50.1 From nobody Sat Oct 4 15:57:31 2025 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (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 3355223313F; Thu, 14 Aug 2025 15:40:46 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755186048; cv=none; b=rvC+V77G8DV2lnwQSmnCm8iqdRC3LGJGbadzqTIVDQ1bQzSOW4rg5TQvmqjQ3bimJ4KVJDS9YLkTgAPBVyYg9BcOYPS8ZxF43JoSAUYYbUri883s6Y5DZqTfJaMRitM1coixhDOh4/PHQQKkyOW5ajNcEGnndePEJTzQDBegPnc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755186048; c=relaxed/simple; bh=taHNU4VFd7VdXTyQOFopdCJIV9s+50hr+H2CAnWWCOI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=EdPt/QRcDvftFd/6RqZPy3iKW/Fh6f3E4u4Q4Mnoq9Z0jK+kMH8208ysnd07Uzxdg9K4pnMEZJeyZlj8oHH2qTyJcwiAwcsrXHN4GbhDcEPaiygez7otJhu+hJb2d06QoLxoBZyhoEo42pqIk8xzNl4HS8OsXV9HF/HSkL4h/kY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=F9Qxj7Kn; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="F9Qxj7Kn" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 3045A40AF5 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1755186046; bh=6d6Q/SQ4sl5V8NWDEJS4x1dcU36x0P3VKVqk7hJ38eA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=F9Qxj7Kn3SolD2gBj4eLFUrNgUvfRQJ/NCAJmrltj0Z8KI02d+PxFsXXbxms5DcKF p7tkois6KlhYby3Dxipy4em6Q84lHHDjnH8aXBbjsXrqBW7WKrX11lDe/4+fg24V2T B1DdOyb7Qa94QWC9UL14Kdb5oYZcBpi3DErMiEyMAu5cJevWHgYwvd/kj1/RboqWUN MakvPHw3aKCrLnUPdJC8i76FM13gvSScfYuZU8Kb8dO/AhGoxDE/5/GmE/YAZPBnwz PU6uoz/qk4aK3+PSFr41S+5QuU14qOPVu0u/zb6tUUvgbcxDv2UrGKu4ZweRriwOSt U4ZU5c1R8TM9w== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 3045A40AF5; Thu, 14 Aug 2025 15:40:46 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH v2 2/7] docs: kdoc: tidy up space removal in create_parameter_list() Date: Thu, 14 Aug 2025 09:40:30 -0600 Message-ID: <20250814154035.328769-3-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250814154035.328769-1-corbet@lwn.net> References: <20250814154035.328769-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Remove a redundant test and add a comment describing what the space removal is doing. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 96e3fe4ec431..53051ce831ba 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -545,12 +545,14 @@ class KernelDoc: arg, declaration_name) =20 elif arg: + # + # Clean up extraneous spaces and split the string at comma= s; the first + # element of the resulting list will also include the type= information. + # arg =3D KernRe(r'\s*:\s*').sub(":", arg) arg =3D KernRe(r'\s*\[').sub('[', arg) - args =3D KernRe(r'\s*,\s*').split(arg) - if args[0] and '*' in args[0]: - args[0] =3D re.sub(r'(\*+)\s*', r' \1', args[0]) + args[0] =3D re.sub(r'(\*+)\s*', r' \1', args[0]) =20 first_arg =3D [] r =3D KernRe(r'^(.*\s+)(.*?\[.*\].*)$') --=20 2.50.1 From nobody Sat Oct 4 15:57:31 2025 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (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 A4DFA23BD1F; Thu, 14 Aug 2025 15:40:47 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755186049; cv=none; b=i5/Gi6LbzJplxH5S5cQcC4K0tvEbIT9AX/xnl7lLDBuw1M6DMu0dIrL81D8gRPAUUSVobp6clssquWVG9L2OnnRKhGNGXBx/NqBOoeO5SGKpphaRp1S5sawX/KtsK1jO2WbEJ18h36rqQKEMI2a2Fuk0A24/reUCiocIctnQBy8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755186049; c=relaxed/simple; bh=4iEX1t7jEAeEe7ybDdIUVO/vmvtgOs+kPaaWmmIsuiM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=j82a155nCYIFN5e0LSv5uaAwTRrffmTJpaqFghMevv1ftyjP7kst7VqQo8MK0izZA+hOhxyI9Zqt6pKfCsAk3bDhnnCrnF115IhWmPBCfp9IHCri+kR8IBOHfNNCSUrayUpa30i2/SEcl4ai6wEcvzTxFmvAn1/IcT0D9YxKpPE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=FBZPQJzv; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="FBZPQJzv" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net BA71840AF6 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1755186047; bh=ZAeV3z1UZGaVZP5QfUsLli80+tuX1mZukp23m87DZdM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=FBZPQJzv7WIpwqAuznJZGNOXeLk0+ZG+QyvGgKmoxlwQrOKflW6zKRD9NI0rzFND/ tTGJ6L7dxDBOmG2qUZqrvXuO5Ebd/A6cjXekvHvAFPdGGsNmEds/ToJuSXUgtqLI3w 7Z37Sjs6drj9Rvln6/7zCoctn4AuoOmCTUcvXzNOUQBtabdtQcvHkSsPTpIBsziMhy tWPwKPt3zohJhsP5lBb2rR17lfYCyj/jM9809Xh1x3Z/Yw7ZcarkV+CLe7RPM9xoiS NF+7oxrSQRZgWkDMZLpcHk4BaIc+4IeG7cwBqKvkhBToD9WoyEnnLNQ6mvOecmog/Y okPMyESANeU5Q== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id BA71840AF6; Thu, 14 Aug 2025 15:40:46 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH v2 3/7] docs: kdoc: clean up the create_parameter_list() "first arg" logic Date: Thu, 14 Aug 2025 09:40:31 -0600 Message-ID: <20250814154035.328769-4-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250814154035.328769-1-corbet@lwn.net> References: <20250814154035.328769-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" The logic for finding the name of the first in a series of variable names is somewhat convoluted and, in the use of .extend(), actively buggy. Document what is happening and simplify the logic. Acked-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 53051ce831ba..07234ce04409 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -553,18 +553,18 @@ class KernelDoc: arg =3D KernRe(r'\s*\[').sub('[', arg) args =3D KernRe(r'\s*,\s*').split(arg) args[0] =3D re.sub(r'(\*+)\s*', r' \1', args[0]) - - first_arg =3D [] - r =3D KernRe(r'^(.*\s+)(.*?\[.*\].*)$') - if args[0] and r.match(args[0]): - args.pop(0) - first_arg.extend(r.group(1)) - first_arg.append(r.group(2)) + # + # args[0] has a string of "type a". If "a" includes an [a= rray] + # declaration, we want to not be fooled by any white space= inside + # the brackets, so detect and handle that case specially. + # + r =3D KernRe(r'^([^[\]]*\s+)(.*)$') + if r.match(args[0]): + args[0] =3D r.group(2) + dtype =3D r.group(1) else: - first_arg =3D KernRe(r'\s+').split(args.pop(0)) - - args.insert(0, first_arg.pop()) - dtype =3D ' '.join(first_arg) + # No space in args[0]; this seems wrong but preserves = previous behavior + dtype =3D '' =20 bitfield_re =3D KernRe(r'(.*?):(\w+)') for param in args: --=20 2.50.1 From nobody Sat Oct 4 15:57:31 2025 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (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 4EDA923BF96; Thu, 14 Aug 2025 15:40:47 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755186050; cv=none; b=OogJPKS42Lx9ZL4QdG+HarDvm+tr/Fu585blDA0F+UJ+dhsRFGA7tNj5UdPfPFyvRc8VBOTLglfigaG9MKHHbpa3vXYhE+qTAeHIXlxQj+fqAgLiLKTvb4Qbb1IJSVns6IGMdmbo664KuLLg1IF9tH/XXJOjbdD51c2w3fIlC+8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755186050; c=relaxed/simple; bh=QMP+A6RZgqavqc1dXbtilnnyb8HnkdEJ1fmcIb+VkV4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=jc/Mh/cNuFimWnTT4Drs2yTab7p9eLBkKDRFtAUQUrUpY9UsU/8kM0jWfBD1ucTIfDMRW7klAfx6gKi1UGxPQ7MG8HX5/4JDW9V5CjrwLy+Nbqtovw/WNr1BSwJ1Vc2coXKvDEZ308GmrATOUJQpps3sMWtYFTqWEpg9aCsXD9Q= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=FhrkEXq6; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="FhrkEXq6" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 47C4B40AB4 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1755186047; bh=MrbbreIikBSbVzvRnFELl6mnrF8Yja7sRNIT6v6ZGfs=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=FhrkEXq6FWkRr25ezR0I9p5Y0HDEQLDTH/8Gxa7HMFHOUH3p/aLieoEflTzD6Jjb5 tskOEgEvCsZr461Tig7kQT+Rb114oAk65XOgIToQdHtMEWvDwT0PBlgzc6aK7S/cFX FrR1/w51l1brjEXqb/9cq/yZWKS+JQLOeswhM+CvDrGLTAqil4RjlSeFv9IYr3TEAI ine5MHutiue/hlEtUDZy3MRSH1b+MGhYeB//aVVQ/jO/jx4p3fk2UKICdlwmv0ExZz Wj68HPeJPhgRjFD+dLj03qDLTNmPO5SDhtXzXLLrQk39Nw9odElXAaVheuiOOY6Mrh Mi1a+lw/4Q7+w== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 47C4B40AB4; Thu, 14 Aug 2025 15:40:47 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH v2 4/7] docs: kdoc: add a couple more comments in create_parameter_list() Date: Thu, 14 Aug 2025 09:40:32 -0600 Message-ID: <20250814154035.328769-5-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250814154035.328769-1-corbet@lwn.net> References: <20250814154035.328769-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Make what the final code is doing a bit more clear to slow readers like me. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 07234ce04409..29881757bf1c 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -568,12 +568,18 @@ class KernelDoc: =20 bitfield_re =3D KernRe(r'(.*?):(\w+)') for param in args: + # + # For pointers, shift the star(s) from the variable na= me to the + # type declaration. + # r =3D KernRe(r'^(\*+)\s*(.*)') if r.match(param): self.push_parameter(ln, decl_type, r.group(2), f"{dtype} {r.group(1)}", arg, declaration_name) - + # + # Perform a similar shift for bitfields. + # elif bitfield_re.search(param): if dtype !=3D "": # Skip unnamed bit-fields self.push_parameter(ln, decl_type, bitfield_re= .group(1), --=20 2.50.1 From nobody Sat Oct 4 15:57:31 2025 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (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 B2FD623C50A; Thu, 14 Aug 2025 15:40:48 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755186050; cv=none; b=q+sb8WS2EESnV0THHE8In4y3UDchPdg3tDYibniI25KJaGdFJ0dMxlti0X4D8E/g2h5uYBjrkLpEBpVZNGJnMAqFgcyqEq4Qs/2fxAB06Vl9IK9tL0kcfGv0HJ8ui8Op/qpoQaT1yt+vuXs/9TuOGMIe8FfhQV6ru3Rmh3AKheM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755186050; c=relaxed/simple; bh=GdVlU78Y9DzwQcjBjkjX5yDPH7mOhzZ/df9QB+cYA3U=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=iaKFnR+OeqijHiImdAzU8Fe0GpCiIIyuybOj+++88uM0G3i72FN/voddI2KQJ2gtFcB93ItFXPuvyU92D9vaPqODwY8T73Vx+fqrr1pL3UJNoxHKcQu9GPHDCDP92fPWNANF0zcyG8f6KkrPlHmrypf84H40xpMfpWvgkbrRE8M= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=oxP+3qJo; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="oxP+3qJo" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net CBC7240AF7 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1755186048; bh=64xgp67hBLhdwbxYz5yPVU5SQebWB9xbdNy0iYDphqc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=oxP+3qJoAWIK++2ixLgR/+UZ+WrHiqJZgaTIFyY+KVONvZXYQRj2AjI9ha5CvBflu xNX7Y3iKct75walxVInQQZMDWqOUbV9XmiWJED11UmJQ6sPQMeie2TClzhVWhBdCeF VfmLD7t8OALRiJpAUCjQ4mpdPZgYCRMfgGDitH/5FSXhW6PxcdgCgFRKTOtDG7y1NC /G0UuM0yjfM2T99QlGFDgRSw1wmE9L0Md+i3Zc1RFmolgoITz/MN0lD0nkRFm1MlEj 6Z0wQwvVc1oZtPmkcZM33kL+YUE6Ui7uRAObx+s/m8c0HAg4K3yp3dZe6o8kb8UTsQ vr+TYChtfIvBg== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id CBC7240AF7; Thu, 14 Aug 2025 15:40:47 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH v2 5/7] docs: kdoc: tighten up the array-of-pointers case Date: Thu, 14 Aug 2025 09:40:33 -0600 Message-ID: <20250814154035.328769-6-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250814154035.328769-1-corbet@lwn.net> References: <20250814154035.328769-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Simplify one gnarly regex and remove another altogether; add a comment describing what is going on. There will be no #-substituted commas in this case, so don't bother trying to put them back. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 29881757bf1c..7f4d95dd47d4 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -527,23 +527,21 @@ class KernelDoc: dtype =3D KernRe(r'([^\(]+\(\*?)\s*' + re.escape(param)).s= ub(r'\1', arg) self.push_parameter(ln, decl_type, param, dtype, arg, declaration_name) - + # + # The array-of-pointers case. Dig the parameter name out from= the middle + # of the declaration. + # elif KernRe(r'\(.+\)\s*\[').search(arg): - # Array-of-pointers - - arg =3D arg.replace('#', ',') - r =3D KernRe(r'[^\(]+\(\s*\*\s*([\w\[\].]*?)\s*(\s*\[\s*[\= w]+\s*\]\s*)*\)') + r =3D KernRe(r'[^\(]+\(\s*\*\s*' # Up to "(" and maybe "*" + r'([\w.]*?)' # The actual pointer name + r'\s*(\[\s*\w+\s*\]\s*)*\)') # The [array porti= on] if r.match(arg): param =3D r.group(1) else: self.emit_msg(ln, f"Invalid param: {arg}") param =3D arg - - dtype =3D KernRe(r'([^\(]+\(\*?)\s*' + re.escape(param)).s= ub(r'\1', arg) - - self.push_parameter(ln, decl_type, param, dtype, - arg, declaration_name) - + dtype =3D arg.replace(param, '') + self.push_parameter(ln, decl_type, param, dtype, arg, decl= aration_name) elif arg: # # Clean up extraneous spaces and split the string at comma= s; the first --=20 2.50.1 From nobody Sat Oct 4 15:57:31 2025 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (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 1FC0E23D280; Thu, 14 Aug 2025 15:40:49 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755186050; cv=none; b=M+oJsiCBqoEoU3IjKRgMy08l6VjAqZyCJoB4I1WB3BnJbOhBA9q/8sUYeVGW9A2/RPN5rjLLgmY6eJlFu9H9kusPykuVtfoO80AruiWSL8iVUA5EwqchiZkcSPqjp4GPudQy31f8miQDBhLQja+cZRdq+9t+ijNlyJVi/pPSDho= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755186050; c=relaxed/simple; bh=Oqps/HN0376Z+iO1VnPfvkXyHaLfOktPPOgMRRe0TJg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=fKmwR20DQAskvCd3gesKh5H7JYO7RKL8d1Gbu8gc6pBlQacYR9Wco3Aw4fIjqQKIsu81j1IT4/891pyLaXGGmhAmpn7fVCHjz4JmPaU7bdcorTGiT6okZiDM2+rGDpE2jvxZYfZPC3T63Xi+57DGtKKvOmFvk99BEpIrSpFF00g= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=MB0B/k2E; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="MB0B/k2E" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 5A72640AF4 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1755186048; bh=2INnb41BXqyj8VwmOeb4ftIjMI1ezvVXAMGWOSxv3Tw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=MB0B/k2EAOVGmWbrtM+WpnwHy18Q7cSbNVCxyDUJpNQkQ8DaOdSVO45+0ZMGWw18r oxuiJfXLmhXTlBKLl6B0tsiJCgz3ZzFlbGVaRBRral+c+RiCzsxe33XVpLe+ZVlz/n CzMnowm395WWD2BUUF5Sd7sve6e3JeFYLuN2RZ2q1BkhNQztofFydGTnYasx363IlE 4fRLR2uHvvFHTaUwtJiQNmU736CrlZzwJodIR1R82VWFoB/+214WbxOy63o2kPhvm+ 0KWXqcdC4ZVhHlvF/fLj7TY+kpFlBrN/eX+x9H7twTzY7idU1gjRJVPtEtZ41x7QD8 SzFkmniGg09kw== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 5A72640AF4; Thu, 14 Aug 2025 15:40:48 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH v2 6/7] docs: kdoc: tighten up the pointer-to-function case Date: Thu, 14 Aug 2025 09:40:34 -0600 Message-ID: <20250814154035.328769-7-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250814154035.328769-1-corbet@lwn.net> References: <20250814154035.328769-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Tighten up the code and remove an unneeded regex operation. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 7f4d95dd47d4..998b1ece932a 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -511,22 +511,21 @@ class KernelDoc: # Treat preprocessor directive as a typeless variable self.push_parameter(ln, decl_type, arg, "", "", declaration_name) - + # + # The pointer-to-function case. + # elif KernRe(r'\(.+\)\s*\(').search(arg): - # Pointer-to-function - arg =3D arg.replace('#', ',') - - r =3D KernRe(r'[^\(]+\(\*?\s*([\w\[\].]*)\s*\)') + r =3D KernRe(r'[^\(]+\(\*?\s*' # Everything up to "(*" + r'([\w\[\].]*)' # Capture the name and possi= ble [array] + r'\s*\)') # Make sure the trailing ")" is= there if r.match(arg): param =3D r.group(1) else: self.emit_msg(ln, f"Invalid param: {arg}") param =3D arg - - dtype =3D KernRe(r'([^\(]+\(\*?)\s*' + re.escape(param)).s= ub(r'\1', arg) - self.push_parameter(ln, decl_type, param, dtype, - arg, declaration_name) + dtype =3D arg.replace(param, '') + self.push_parameter(ln, decl_type, param, dtype, arg, decl= aration_name) # # The array-of-pointers case. Dig the parameter name out from= the middle # of the declaration. --=20 2.50.1 From nobody Sat Oct 4 15:57:31 2025 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (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 C984D256C9B; Thu, 14 Aug 2025 15:40:49 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755186051; cv=none; b=Gun4M2a4yIV8YXoNEjhC2bTpZU7RH1r2sl4NQs1PNH9f9rmfF0VNjXL2GPZVkIAwEjxRidBMDtutmgkdjTqprSGxIpQO5uqhl6vZtZrK5Lq6DOvA4OSVom/PxB3bceJF/TKKjz8SzQRFstptOodk1Y8Aa7PSfvOTsyRQRZBa4WA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755186051; c=relaxed/simple; bh=Imt/CG95szkbrIF67vvhaiJ3vGrgJ4WnTzwuOgNJ+nI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=aoSoVwBmv3dgwbymSk28w3dmTmvvNNiw4yaSRRnMrB0uThrSV57uYDTRcD49V2SPOYvp/f5PhpyScWFB0RjwS2MmaOECrZroGzYE0pUp5hobnAd2zZpIWmbjJHW3iSVcZBSK5C5dEz0xNJkqcx92fKbQZDvthehf3Bbl/GYJ6wQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=iDi3w90L; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="iDi3w90L" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net DD63F40AF8 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1755186049; bh=+KzKeSXKpgE3Y8aAKGHjfgQDE1GqLmFfPVGjGHQTZD4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=iDi3w90LK9KbYx4MujxXV2GyYr+MNc5f4UIvC2a3pGmFSGXjRA2GTk/m0syoGk1J2 B0RfGYrHycQqRr6Utv1jcD+AkfFkE0maQ+BW126a3rT8MpUWkXNEQz1xWVHTXWvp55 gtEcqSoRpeyQ5I8fjKq7BNXhbi7eZPw/zMCDy1tjTH/gsw7+TxpQKtloFthpC9Gpxb +Lz6eDGuBh9nRHT5qRogvtVpMVYkGri+7H5Wv9Jyu/WsJDqsy8KeyqZ11I+fJZHOrv DaEJuGHEIv6GDj++ZdYDCsg++fG4dRvPo9y7kUAzHsgPv6cOs6FGV2ouGByINHZWpG 4LF21l0PQd4IA== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id DD63F40AF8; Thu, 14 Aug 2025 15:40:48 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH v2 7/7] docs: kdoc: remove redundant comment stripping Date: Thu, 14 Aug 2025 09:40:35 -0600 Message-ID: <20250814154035.328769-8-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250814154035.328769-1-corbet@lwn.net> References: <20250814154035.328769-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" By the time stuff gets to create_parameter_list(), comments have long since been stripped out, so we do not need to do it again here. Acked-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 998b1ece932a..a560546c1867 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -493,9 +493,6 @@ class KernelDoc: args =3D arg_expr.sub(r"\1#", args) =20 for arg in args.split(splitter): - # Strip comments - arg =3D KernRe(r'/\*.*\*/').sub('', arg) - # Ignore argument attributes arg =3D KernRe(r'\sPOS0?\s').sub(' ', arg) =20 --=20 2.50.1