From nobody Sat Oct 4 21:05:24 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 5DE652FE594; Tue, 12 Aug 2025 19:57:58 +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=1755028679; cv=none; b=fTQajLsdV0j3jdKk9AB1gUxXMECsGtCudGnzC4j95JaMlTTm+/VTgvjyJtRSqqnNEJm1OnInJs5BZPfvnAGHx5l9ONtvUZvY7V8VfZVkDe52JcJTXRwbpo5SQQauo9cWKgA1FoEP0A/RYERr75jcZUwkzNNfV8zxFkGZAA044eY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755028679; c=relaxed/simple; bh=4DU+J+rTTiyKivCXoJcHXntfdgk2NjPRT4WF82XNoM0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=j6KiJmvgiOSRSty8BVYNGjAFdtZChQBVHZ2/IDaf7teyI7ug7fyDhmOGkUu8oZOudHYgqmMQXXzhVHYy94B5LIufJtrR89qcVyA2z8fnBZ3XJF2IoZggdQRb5RvU8zhrayDZt0OJj47vVP+8sRmtrdm8L2vXql3jm36gP4zCGpg= 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=DqXh31bh; 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="DqXh31bh" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 70BB640ADC DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1755028677; bh=JFF0dVs9V9DAAxQ+F/q3H9i8XQ3gen8VksquAovDBzk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=DqXh31bhIN7HXdtjAmSEKs2343cRTulew2dAG2lGie+JDZE69azM/ZusYVblZlvZi oNrnLyJI4OnmE0zGm+zVEo57gtPSWZPmOBZHNn8ZlJ4btlOhGaIozUCwsKEOl1R8PM rqNi/Oj+xpIyPkZ8oYfNM0JsFohpS5W5mUy+mAZbDYWranE25WF6IFTILWGPCRJVzl Dxk+WWUXCYUfeCUJNkh7aSp4dtidJKPJnoE6i2wNgrl40e3BlvZ/ASkdKrpgXRaMFC ZYWQFLiz1BRy6e/+sHMcPdyj9PXIRWMWhFpV8W8r9HXH6xrXej3j8+fYWlTtbwVAx0 6JLQVPdFouZjw== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 70BB640ADC; Tue, 12 Aug 2025 19:57:57 +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 1/7] docs: kdoc: remove dead code Date: Tue, 12 Aug 2025 13:57:42 -0600 Message-ID: <20250812195748.124402-2-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250812195748.124402-1-corbet@lwn.net> References: <20250812195748.124402-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. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- 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 21:05:24 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 E8D6D2FD1D1; Tue, 12 Aug 2025 19:57:58 +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=1755028680; cv=none; b=WbJEBSoUXQDQHoa8O/aWMBSKjKIgoH2uACFlVhdZRmsNe4qAX/QYJcym3Wh4/b72lVKldF4eOEC9DeYbs2/NZhxDGg5xgTT5F6RWozdCUDNLvJNV8SxRHSsE0AdjMlE8ZXkwSOFO/UxtDSe1UIOi16AVsPzg+N56pXDrRJHW9qk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755028680; c=relaxed/simple; bh=JvmLJDhjDkB39xb5xa2t2x70gtWreP21qkHEz5iz6ks=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=VDwh8UjX4PcssfMJkiABJNkDe36YO543/i5DDAdDwgerRKTtV70p8u4Nx8W4WoBdYBpyzqivQa9QNJKBIDVHZfasCwzYf2rqwHwQsahuIIzv/tK28NCa+evzF/qMo+bwH8JzEqn7Fhxdz0TFx43yi8P7mZk6H0TTUUo8zy9I9ho= 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=CEhG2j8O; 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="CEhG2j8O" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 0658840AF2 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1755028678; bh=KMPgBSRi3GGUx39cwLfxSPIMnecJC+f5rFtqbGJHi2E=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=CEhG2j8Oc7Gwysox55CrDtRNmoEusNauZPHgXjyw4usw7lPU0TyDGBZh3wSPZDPGO aVDq4F4yJuGBTQzCra0sBiae9U1hGjFqAinItr3HMcRUhcA9zgeGksiKk4iYL57V7X oxUYi0T3mVxZjfjuV0jq2Hwv0LYNihjdAzxDa05JhvC9Ax6fIC41krFS8Mei6pxV7o UZoA4axFb1/1fJzE2syG8inbbW05qFkF3WLHRjnSGrQQUOR/jH9ohbvKtKqLxUe1ax OET60SK1m5aIXk8ai1i19/jMiRpm3KZfSJjf04kB/1/AA5WyfyLPMnV5+eLnLCrwbm cVCM5nMqxFDHA== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 0658840AF2; Tue, 12 Aug 2025 19:57:57 +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 2/7] docs: kdoc: tidy up space removal in create_parameter_list() Date: Tue, 12 Aug 2025 13:57:43 -0600 Message-ID: <20250812195748.124402-3-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250812195748.124402-1-corbet@lwn.net> References: <20250812195748.124402-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. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- 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 21:05:24 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 AACBB2FF167; Tue, 12 Aug 2025 19:57:59 +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=1755028681; cv=none; b=Bnq3xSdCZiLsjaYqpRlRJW+s3F0IluesZrIhELlvhVVov4xFmYJV+0+d2b8W8tz5Cr9dGRWCrt1p1t4C9dyklfYQ4+XK4Vv96nX+4Ns68cGotrgFjzCtDp0P7EjssjZZD2uitha4b8d5s0TgXGfmIjpih2jpfc3JuNJ3kXZiDxc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755028681; c=relaxed/simple; bh=OBhaUtTMbyBlh53qINhRG3itKYtY9IvNRUlFEQmkpv4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=nKDmootcuaJYf8Dkbk2ge16ajhx3wEFRFvKAIs3sLwe40o2LG3eAl2xsQ+yatP/StIX//BtSp7LbMyDtMFNpJ16LttBEMqOQKfusPfuJR5t8h7LM1p/6nnZ7+m9ok5MrH768O1/PjS2/wyP9xve2XI3aKmTIJXfSrBsPFX4ZAEQ= 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=d9aQ/asY; 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="d9aQ/asY" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 95E3840AF3 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1755028678; bh=jGM1icqt6gjQ/B6dtIFBPdZEfj3b0lX+FbDflq8OkGc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=d9aQ/asY3QyX7PGfHp7GQXKL8CtOI9KrlKF4fte9P38M0pDSl80hX4Ele/SUiShTr jv/N6uKDA9UKpqsBOwmdpIQsGq5KBJe92lOTDp2B6oyOQtLiWvFOwO9iaWBjl5LTRP 6pjGlchmY0WRtGZnNxpc/kXQPEwH2Vwz8zRQja/QfehpLhSmy8p8LM3Dpj28902TPg Syex+gPfGza0XMkGYu5neJAf4mWwwab0mLLRtPYjUQ7BDHWXHqnBKH86qsjA9Anw2V JyafiAcfL+8oZt3V3zLNo/CzJ8otLE8jMxrnsNSVE1wD06wl6V18+AbNipqdc7sCgb miCaiTOyN9PJQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 95E3840AF3; Tue, 12 Aug 2025 19:57:58 +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 3/7] docs: kdoc: clean up the create_parameter_list() "first arg" logic Date: Tue, 12 Aug 2025 13:57:44 -0600 Message-ID: <20250812195748.124402-4-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250812195748.124402-1-corbet@lwn.net> References: <20250812195748.124402-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. Signed-off-by: Jonathan Corbet Acked-by: Mauro Carvalho Chehab --- 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..47f7ea01ed10 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+)' r'((?:.*?\[.*\].*)|(?:.*?))$= ') + 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 21:05:24 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 049D82FF179; Tue, 12 Aug 2025 19:57:59 +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=1755028681; cv=none; b=LfCurcgshPT2uMabYjn+VfY1g9Oql2xtMOkbi23ERPRq7YJzH/pqrsQrN/C3VNz/SE0UVY7/wbsaEJ2VGu35g1UPGwpbVKW6x7rcikVyuMZH9JXw555XC4M8vAe7SLxDRdozbMgH9gq/atdhaBSOGqdquTTElIG37Iz4JhLrIFo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755028681; c=relaxed/simple; bh=rjJmmU5S7TbIUqYY/JAO40jGyx07vxve6fsT45iwmjI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=iwa9QInoa/7/1WxBV8QgKvs4o1qTM8jtQviAaUHL1jjSmtNEKeP+wis1TjgyE5RAV17lSssbnuXJ1uTLiXQQVg5nLhKdMCZyfWVZdTHhU0XrXclW5Vch0F0gCd11iFoR9o5P+laZ4teZML2s2p/23v4wWcquSyd3VkfzarwTJaE= 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=kNgdjhMu; 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="kNgdjhMu" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 267D640AF4 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1755028679; bh=J57bzfXmOD2R1gP/y/AesBfePH55ilhwvePByC8Qo94=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=kNgdjhMuC+5IoejMTX1/jr4wwxBXkZYm6lDQfJqWB3hI2thoNbBSRc0etNjYmlMX2 x2KUuArH3y59ymvQmmqmyvf0W0YP9J9ftiLxOFNqQaFYXgk5n/yyibnEY0VOwW6Pai BJfrr02cVuLTp/pfbzIepR5NRh26qhxIfk81EGP65JB2wGbW4mp2yOXpMh9OL77yRW Lf8hafbT1Ty52/ev++N7cPV6OnzT2eNanQMqw1+BgZ9Jpo7sno6OFNjxC2RsYqSSJI pKZjFTvs4MElqfFKi1vIx2DVnP1zpHwC0RicI+o5lermwfJeh0OHRCga6uCmTqQGpG 4ef1sdcEUKffw== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 267D640AF4; Tue, 12 Aug 2025 19:57:59 +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 4/7] docs: kdoc: add a couple more comments in create_parameter_list() Date: Tue, 12 Aug 2025 13:57:45 -0600 Message-ID: <20250812195748.124402-5-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250812195748.124402-1-corbet@lwn.net> References: <20250812195748.124402-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. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- 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 47f7ea01ed10..36c4035343dc 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 21:05:24 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 99EA02FFDD7; Tue, 12 Aug 2025 19:58:00 +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=1755028682; cv=none; b=lzIFx84mB4Kfrm6cX3xkl8AnD1lDoNprRbPv9dLL05j95AGhO9B9JqdPuCW+HZBuPxGNx08nqBRq34GTFrw9omMYxGYqvU81g5utBg99ymIjI4zYAm9rGpcc65eYaMK+7cMi3tlme3yOiwXL/vv+Xwijw320eI73AcsUQPNP2Vg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755028682; c=relaxed/simple; bh=V1IDGL8cFlZaKVSCaLX9tbLB7CYsTMuCCYHx4ufoRas=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=LH6GXJRjH4b+d+uO6r5uZ33ng3hAEy3maBWFmR75ee2qGibYqVlUi8+jnlSnvHGcFGoZl6HHuirUKnEVITHMq8VoHSK99o9BttOofX63dnQdk2DZK1SaWg+khfJhK+wAiMz5SnaQtll6BBn78VAY35xQE0rP38ev04L2IUZL98E= 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=JzKI3t2g; 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="JzKI3t2g" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net B058440AB4 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1755028680; bh=yqlFTUjm2yToir6qAqz3bh+1fa6rWAIvKLsj0oc3CbY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=JzKI3t2gzK0r6gGqKxFPeaCEynl348Bs1JwlWWCPdZWwzzENerdsIlaO1jmUF52+N KoIa27SBFLt9oiz+J/2Xej68v8HvQzm3bgxO+RdfyKJ/BY5/h20b76kg9iTHZYdXPc ++R9EdI99xkUxjFtWJN7/gKyfIjPqUlIHwEc3KhAgjrOcUUJINC1BGqdjpdY6W90Kw sQrVPT3wqsXisvC/RQMUfGO1CY8ENYJqYAi52/aVXZA06z9DDRSXXFKJfKzPRqKGAy UixzQ0qXrWBtZ1hYuvQiir0KewLFWSp3+R+VBAV4m/bYmtSwkTyU9pk3dqZzQyWTBd Fk0tP6UW/URoQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id B058440AB4; Tue, 12 Aug 2025 19:57:59 +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 5/7] docs: kdoc: tighten up the array-of-pointers case Date: Tue, 12 Aug 2025 13:57:46 -0600 Message-ID: <20250812195748.124402-6-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250812195748.124402-1-corbet@lwn.net> References: <20250812195748.124402-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. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 36c4035343dc..d7fb79a64487 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -527,23 +527,19 @@ 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*' r'([\w.]*?)' r'\s*(\[\s*\= w+\s*\]\s*)*\)') 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 21:05:24 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 22C382FFDEC; Tue, 12 Aug 2025 19:58:00 +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=1755028682; cv=none; b=jKjqREXghJ5ZdnDjIuV73zlTKsfEKQF2dZZrQ8m7Yer6c2QYQ7W2X3PqlV8106znQe9NhutSe/PoGegr23VurZZ+CmnAGgJPJLVTqbpPsUDbM7G240MIYlrEwBlHqKlrFHSCvEEgYK300Z0eW0rqDoC7FwI1Y+ryU9Fpi3Ai75E= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755028682; c=relaxed/simple; bh=C6Q02unUU5uqvZL2/9uc58UlOCZiLYQ1uBvC+Z6nOh0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=m7g/9r3jrfF8l/xcvT/BkxaPWWErnZYbiGxdKEASJjukeHFh4RRwY9yP9TEZ9egojZIPN9UdLZe1kDRTORwa7t4sbRj8lUA1wz9C80LftCimgw7XHQpTawsjKhEa81XlZTzEgwECK+wx+kBSJk4jZiJVglI4iQuOuyCX3L7qif8= 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=quTH9lIp; 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="quTH9lIp" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 3C79C40ADC DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1755028680; bh=P3NYcSVz8WaB2qHPWOisuFhEeyE7SQzDs3q7Nm4jogs=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=quTH9lIpyBYJz2j3gx2Hq68BaKtaNwLyEpVfasrMHKrlvPJ7L8znrYD9ntiZABqQT vBTBxYklWeb78aa8aX0Gq4aGIdneZq4uus8ESXaujDI54jjSCw9gYuNT2b87ZWBUtS aRf5XIMiomB4LOO9kiPKPLfmV680sY/sVobvqmJRCC5KtysZabPdOwW5HxGa40CTjs AGKoBMyButowQk0Z1Oszad9tv7w26uoEDCJSs6rpkqrsBzE96qTwkYo1KDGumBluZh GXn8X3BtB+l90bqR6Ca/9lC8suz4bX07AuQwp9KyIo//kFg2DginsQDHJDUkFOxD7K F74sm6lvuJE7Q== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 3C79C40ADC; Tue, 12 Aug 2025 19:58:00 +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 6/7] docs: kdoc: tighten up the pointer-to-function case Date: Tue, 12 Aug 2025 13:57:47 -0600 Message-ID: <20250812195748.124402-7-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250812195748.124402-1-corbet@lwn.net> References: <20250812195748.124402-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. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index d7fb79a64487..ceb38b59fb4c 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -511,22 +511,19 @@ 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*' r'([\w\[\].]*)' r'\s*\)') 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 21:05:24 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 B37CE2FFDCE; Tue, 12 Aug 2025 19:58:01 +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=1755028683; cv=none; b=NBxRmojeEZJqJOUrgkP3xbcnTrGmEQ2N47H9t7jx59WDIZ+xc/pNRQHjCVUFq42HYF94Eo1FljYAqOJnEcSmZqIxFkl/MUx4/g1mRJoFyGiNJ7/a3ZD3T4VawMIQbyt321Rs43njsgj5n8sty2JtZrAjTyMDj/6P2Roxg81SIdg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755028683; c=relaxed/simple; bh=6CJmY3IW71l9TEnPoaKlO72qFoTlTKL4KzRVZaA35Wg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=CEbZu6eTYS/8Y2uIbjaWdAsdWvUOaHWXu9a5c5Z25rU1WrGp94Cf8FcSDKMoLPEHypzqHczORIg4SkJLvS2UNsLrZVMn3iGpLETyRxN70woMtSXdXxMQmIZ6fptUOSVHFG/FlayaxUGnsARAW2rQ26rCJIU0wja9bS2oR58TfWA= 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=iD8WHfQC; 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="iD8WHfQC" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net BB99B40AF2 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1755028681; bh=BxEDE/rOZa6PWm+lof8pugcQbiDcFc1q2RqRsdRX22M=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=iD8WHfQCADQzePwu80d7M327ijfnLKGdLVmKikPMMbkNlmies/uUW1vxTMic+mZnO S/udOxeDvtW0rOCLma3tEfPZJUzR15xqkR/mtowQY/LPAxWNDU1hZG8yks0mb0jVlU Q4MXTCkx0b8fh/u+q3qYRti+ZzGIQ4yhiVjE1SxOvnytPcRMjJTMM4gu5iNkZTropn EbkXMnfIMtKlc8Mw6wv/VasxP/EDYkUG/AXg3UEWvO2Um2R5bU492ZjJpxtbzW37ip KxH4Jw5jUZ7VcNYmFNgfFaoWraJAbXpVA0SyhCyDmb4CRHttjJicyzoWHfR1VgaANT 0WJXVBQU22HQw== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id BB99B40AF2; Tue, 12 Aug 2025 19:58:00 +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 7/7] docs: kdoc: remove redundant comment stripping Date: Tue, 12 Aug 2025 13:57:48 -0600 Message-ID: <20250812195748.124402-8-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250812195748.124402-1-corbet@lwn.net> References: <20250812195748.124402-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. Signed-off-by: Jonathan Corbet Acked-by: Mauro Carvalho Chehab --- 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 ceb38b59fb4c..900c028687cc 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