From nobody Wed Oct 8 00:25:48 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 E9E9D2206BB; Thu, 3 Jul 2025 18:44:15 +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=1751568257; cv=none; b=YjVqOxg6akNVCkDb+eplt9MuOb4aHbWLCdyFW+WIJJ89IKD7C+/DmCBtBPOZVAzCe6s9s0Ma6bqaCwhS8ueadmD3tv6UJf0BRiF6QCCS1AXbkbGy6nHROVA52OWTwpNdKT76A3qFFZucMOPXPZOWHrkjHeYCsnZ1dNNGT91nNCA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751568257; c=relaxed/simple; bh=VpaXimC5GQUFOAKQq0XZlnZZj56JFjPMmcx706/uE2g=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=FeGjTf9f+oVHAolf2JL57+KWNbLvtNtofOhopjJpnPdeWLqjNAYrKuAw8TM0nVTe/XFHvpEBeuCp9VAcDU7ruWW783ROzxjed44G/a9czrYH580PZFGIdJWRqd0Ea8iOHW86vtYWG5XM+6QlZy5dTfG0zqkLjt+iGhybRYLxbF4= 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=g0pMZ4K1; 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="g0pMZ4K1" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 09FB340AC9 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751568255; bh=tduV3AIErAq0XBbPXSaA0O0GHSM31AJpVFRmJW3UCGw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=g0pMZ4K1Z/8OD6yxbdDFK6kOpgi66vNnyWwZnkqojJbNJyufPCXqj/V+qNSOpZ09W 7uWQ20zEUdShU+xclkth9x5DOuln2MdMuc6HFkI8I52cR3Fr6gp0d/NVGJJsDnwZAY jvKxDp2F/oot+YznJ3Q4kEQT6TElhbJkU1mGbvsHe3OHONWEkKOE237PtN6OBUByUX vD5hUiLeafFa2V/pAu6asUwqxn95Si02oFkHR3Wtlrq0rMz7rLw42jNeY+eLmQYk0d OW0r4N7fmfwpeY3KDjnLo8+4uaiCPKJJvBVXvOXlMOTYSGJ8hxrnzXKofsUuMn/PHd Hem2pIwjWk3hQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 09FB340AC9; Thu, 3 Jul 2025 18:44:14 +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: don't reinvent string.strip() Date: Thu, 3 Jul 2025 12:43:57 -0600 Message-ID: <20250703184403.274408-2-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250703184403.274408-1-corbet@lwn.net> References: <20250703184403.274408-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" process_proto_type() and process_proto_function() reinventing the strip() string method with a whole series of separate regexes; take all that out and just use strip(). The previous implementation also (in process_proto_type()) removed C++ comments *after* the above dance, leaving trailing whitespace in that case; now we do the stripping afterward. This results in exactly one output change: the removal of a spurious space in the definition of BACKLIGHT_POWER_REDUCED - see https://docs.kernel.org/gpu/backlight.html#c.backlight_properties. I note that we are putting semicolons after #define lines that really shouldn't be there - a task for another day. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Tested-by: Akira Yokosawa --- scripts/lib/kdoc/kdoc_parser.py | 27 +++++---------------------- 1 file changed, 5 insertions(+), 22 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 93938155fce2..d9ff2d066160 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -1567,17 +1567,9 @@ class KernelDoc: self.entry.prototype +=3D r.group(1) + " " =20 if '{' in line or ';' in line or KernRe(r'\s*#\s*define').match(li= ne): - # strip comments - r =3D KernRe(r'/\*.*?\*/') - self.entry.prototype =3D r.sub('', self.entry.prototype) - - # strip newlines/cr's - r =3D KernRe(r'[\r\n]+') - self.entry.prototype =3D r.sub(' ', self.entry.prototype) - - # strip leading spaces - r =3D KernRe(r'^\s+') - self.entry.prototype =3D r.sub('', self.entry.prototype) + # strip comments and surrounding spaces + r =3D KernRe(r'/\*.*\*/') + self.entry.prototype =3D r.sub('', self.entry.prototype).strip= () =20 # Handle self.entry.prototypes for function pointers like: # int (*pcs_config)(struct foo) @@ -1600,17 +1592,8 @@ class KernelDoc: def process_proto_type(self, ln, line): """Ancillary routine to process a type""" =20 - # Strip newlines/cr's. - line =3D KernRe(r'[\r\n]+', re.S).sub(' ', line) - - # Strip leading spaces - line =3D KernRe(r'^\s+', re.S).sub('', line) - - # Strip trailing spaces - line =3D KernRe(r'\s+$', re.S).sub('', line) - - # Strip C99-style comments to the end of the line - line =3D KernRe(r"\/\/.*$", re.S).sub('', line) + # Strip C99-style comments and surrounding whitespace + line =3D KernRe(r"//.*$", re.S).sub('', line).strip() =20 # To distinguish preprocessor directive from regular declaration l= ater. if line.startswith('#'): --=20 2.49.0 From nobody Wed Oct 8 00:25:48 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 810332F2705; Thu, 3 Jul 2025 18:44:16 +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=1751568257; cv=none; b=l0ywv6m4KxT66VWp+2QHm61ruE8UsQTJUgMsBzfAP0KwVeiv/xO4bCHtdM4OVcIN4nPCeOHHCG8OgqcMYHEe7jhy651IPgXJ5rCW3nnvy3byPXgT1uQOOBLhWKNbx+JSIr0NnFmb1jzmBLBWgR29TtIPyd26tlbmi0c9yVka8zA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751568257; c=relaxed/simple; bh=0hR6ZhiubZ5Kyc6vmfw/sHaL3W5BBzzHhyzQChARWQk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=oabJUyYAim6z4s7XgfTpTTkQ7buamf2XECrsOgvZR3bM2yr6J0Ld7Gb8jjfg4aeuRXKdrxoLyZOJrkPXmgQ9iN4wrTVmgkX78LPGC+Yf4GmohNe2Jhp30Gt5GIdXwkBEZYtlIY/obGqMjbrWvQ2vS3eez1dYcl69RUKxlQvbjYg= 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=oCr03uAb; 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="oCr03uAb" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 8CDC340ACB DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751568255; bh=+7QrIo1J84pby1WL7DeMQCAy/1LzFtVjNscgsF5i0jQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=oCr03uAbFKL4p/BPT7UvcaUbllWSwHwVPiLNAXv75T35XXTV0Ahic2EFcUC3zo+hR TX9399/p/Y/+pgJlJNPRaf+CDn+XgqON3RgJlaBZaxk6x01P86dlTYZ2jKkUjl7nEz s/qH2kWi2B3LSkcQtGN+a7d8O8G3wlcX5pcHOVcl4MCsA9O5AHL7evlGawF9F9Q7Jj oQohgSNNFADuObgGnUxIplZANSFMbNxVqP7M/Ih99QkFYBKsi3Z6XhFxPjMP6K4GqT Vl4ql8MzNbwRkVMaMmDEmFtCHtrai+3jLN4RVcNpoNXt/S44FAek1G0KR4GWBx120W CY7RfW4fjtKuQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 8CDC340ACB; Thu, 3 Jul 2025 18:44:15 +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: micro-optimize KernRe Date: Thu, 3 Jul 2025 12:43:58 -0600 Message-ID: <20250703184403.274408-3-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250703184403.274408-1-corbet@lwn.net> References: <20250703184403.274408-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" Rework _add_regex() to avoid doing the lookup twice for the (hopefully common) cache-hit case. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab Tested-by: Akira Yokosawa --- scripts/lib/kdoc/kdoc_re.py | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_re.py b/scripts/lib/kdoc/kdoc_re.py index e81695b273bf..612223e1e723 100644 --- a/scripts/lib/kdoc/kdoc_re.py +++ b/scripts/lib/kdoc/kdoc_re.py @@ -29,12 +29,9 @@ class KernRe: """ Adds a new regex or re-use it from the cache. """ - - if string in re_cache: - self.regex =3D re_cache[string] - else: + self.regex =3D re_cache.get(string, None) + if not self.regex: self.regex =3D re.compile(string, flags=3Dflags) - if self.cache: re_cache[string] =3D self.regex =20 --=20 2.49.0 From nobody Wed Oct 8 00:25:48 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 071052F2706; Thu, 3 Jul 2025 18:44:16 +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=1751568258; cv=none; b=tQENx87rgFzR8WdvVjzv5KXNyTI1I9CsXJCH/DNw21YO+bNe6cWcVgHulPpz6oiC04HUkIaGJ8ZYpjEx3Plm2SkEz3M4nSwAkUcnJrrDR9zfeMGYrePn/5uxXlGDu64XPpJLk9ttm/tuUq1X6IqKL0/Gr3D35ZEtZEr6RfSrZgY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751568258; c=relaxed/simple; bh=8LpVR5vjfFVmOAAZmoulkR5XIUYLW27aeF/9waSxwdA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=diiEYXKU8ckYziirLnMo7BY5JYRxdJefm/lluDfpiIlCdQeQ2PeIx5t6Uf7Ra+CoqHq1/ZKbuNMCUpwSd+s8Zi92Zd6pppfsRy8d5aQr/nzR1TyMRruPwgkgPM/3D/+XAESPGBd19twTMW7T3YZSz7AuN9/W/t4yEvzJ2pZul54= 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=QNze9jn8; 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="QNze9jn8" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 2260D40ACD DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751568256; bh=Boes/PYNn6MSOnmyVvyWWb85WBr7EHHbGNkvn9wn+Ok=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=QNze9jn8rGBt3zujbwDNW4UdhaCkJ+fuPpT7nVEi+Yr5JT9MPSttNCJBwtmiOhznB elHFLJYRIwvu79SwmzPCdEkxNT3o0MfAY8eBu23e7Dvq29Xz4LNz1bXFBP3ce+4Unm ImwnLb5XTxLPSmr9OXiHYCNvk+labhrrnv3IEuPd0wmdPITHsZiW59Jr20AMOHcNAC g/ErG5fzTr0jdDmSQgcz5EtoUwaq9F52VS0COeJjNBwkf6bHt9XIIjj+AELTahuXA+ lZRx5RoPT8WXrTzLwQ7+vFr42HEU5csim1QMzaDE7qlHyrgEevY8vUPLp8XCqymtmm tqdHIYlB2aXqA== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 2260D40ACD; Thu, 3 Jul 2025 18:44:16 +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: remove the brcount floor in process_proto_type() Date: Thu, 3 Jul 2025 12:43:59 -0600 Message-ID: <20250703184403.274408-4-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250703184403.274408-1-corbet@lwn.net> References: <20250703184403.274408-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" Putting the floor under brcount does not change the output in any way, just remove it. Change the termination test from =3D=3D0 to <=3D0 to prevent infinite loops= in case somebody does something truly wacko in the code. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Tested-by: Akira Yokosawa --- scripts/lib/kdoc/kdoc_parser.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index d9ff2d066160..935f2a3c4b47 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -1609,9 +1609,7 @@ class KernelDoc: self.entry.brcount +=3D r.group(2).count('{') self.entry.brcount -=3D r.group(2).count('}') =20 - self.entry.brcount =3D max(self.entry.brcount, 0) - - if r.group(2) =3D=3D ';' and self.entry.brcount =3D=3D 0: + if r.group(2) =3D=3D ';' and self.entry.brcount <=3D 0: self.dump_declaration(ln, self.entry.prototype) self.reset_state(ln) break --=20 2.49.0 From nobody Wed Oct 8 00:25:48 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 876F12F272E; Thu, 3 Jul 2025 18:44:17 +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=1751568258; cv=none; b=d5dOD7s42x3wfz6W0Qo5EKtHHphCbewQrXETwyggKYXOY3O1dEFrKgpARRPFrWxYCGO5kzAoXYEGvwXjsQXZAeDP0zkgQRjexgEmFFSiDYuxO2kJZ1J2kkmJOa4U6uoJNtmdyC3jy/Xsmp9mmH0BXhtSkDddbJLwpBaO5mEy1NE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751568258; c=relaxed/simple; bh=GkG1vcG7XhGcUSdNrA6zdkdLxMcOkR0H4rbcmrTFcc4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=jYJCE+iK2WqieXHhE6ab+ZM1Dk7B/CLNfEjajb2hiPMpqjXRXsA9ntALegy04zq7NJDp3c05AXebY0DVy92hd/f6HwDByvtgvPg7yl+MYhcW0ij9mnN1eb8Ybr29p40ZOy5RRqqlRBDgIjy1MEgGDmQM/WGRJlwfqRBiikmE+IE= 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=PwnakXp6; 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="PwnakXp6" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net AF11440AD6 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751568257; bh=Ht7j5bPcQZEQ3B0MbNRUh1mM8iQ6b/SWlh5C5aYnfiA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=PwnakXp6K1pRO+SrrcXSlIBrMg29sZIlm8QY/++md8VVUcSrf/OTbBJCqMSKNRW3V ukjDPF7+mVe4Lm5kLazHpkJOqKCQ/bPAZMEppBvVmyJG3a+5oOfWouJqAKBXuY/NY9 rS5j+fgrYrt+xvHauUmS0SI14TuEtm8NXrQe/oQduY2Q01CS1SuASpf5p7jvlc11S5 9Yt8ZrbDbWZTm47AocJ7CVRlADNBLtrf9P3G69YZM+IEV/396+hxcw6k/KjZzOCcny n1fFqzSyyTmSX7HFXaVPm/mGvj+wsSNuyeFogaGQBbW4TTccYMu7pIAk5/24S2Rw5M oIHMCMN1q425w== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id AF11440AD6; Thu, 3 Jul 2025 18:44:16 +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: rework type prototype parsing Date: Thu, 3 Jul 2025 12:44:00 -0600 Message-ID: <20250703184403.274408-5-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250703184403.274408-1-corbet@lwn.net> References: <20250703184403.274408-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" process_proto_type() is using a complex regex and a "while True" loop to split a declaration into chunks and, in the end, count brackets. Switch to using a simpler regex to just do the split directly, and handle each chunk as it comes. The result is, IMO, easier to understand and reason about. The old algorithm would occasionally elide the space between function parameters; see struct rng_alg->generate(), foe example. The only output difference is to not elide that space, which is more correct. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Tested-by: Akira Yokosawa --- scripts/lib/kdoc/kdoc_parser.py | 43 +++++++++++++++++++-------------- 1 file changed, 25 insertions(+), 18 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 935f2a3c4b47..61da297df623 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -1594,30 +1594,37 @@ class KernelDoc: =20 # Strip C99-style comments and surrounding whitespace line =3D KernRe(r"//.*$", re.S).sub('', line).strip() + if not line: + return # nothing to see here =20 # To distinguish preprocessor directive from regular declaration l= ater. if line.startswith('#'): line +=3D ";" - - r =3D KernRe(r'([^\{\};]*)([\{\};])(.*)') - while True: - if r.search(line): - if self.entry.prototype: - self.entry.prototype +=3D " " - self.entry.prototype +=3D r.group(1) + r.group(2) - - self.entry.brcount +=3D r.group(2).count('{') - self.entry.brcount -=3D r.group(2).count('}') - - if r.group(2) =3D=3D ';' and self.entry.brcount <=3D 0: + # + # Split the declaration on any of { } or ;, and accumulate pieces + # until we hit a semicolon while not inside {brackets} + # + r =3D KernRe(r'(.*?)([{};])') + for chunk in r.split(line): + if chunk: # Ignore empty matches + self.entry.prototype +=3D chunk + # + # This cries out for a match statement ... someday after w= e can + # drop Python 3.9 ... + # + if chunk =3D=3D '{': + self.entry.brcount +=3D 1 + elif chunk =3D=3D '}': + self.entry.brcount -=3D 1 + elif chunk =3D=3D ';' and self.entry.brcount <=3D 0: self.dump_declaration(ln, self.entry.prototype) self.reset_state(ln) - break - - line =3D r.group(3) - else: - self.entry.prototype +=3D line - break + return + # + # We hit the end of the line while still in the declaration; put + # in a space to represent the newline. + # + self.entry.prototype +=3D ' ' =20 def process_proto(self, ln, line): """STATE_PROTO: reading a function/whatever prototype.""" --=20 2.49.0 From nobody Wed Oct 8 00:25:48 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 0EF2C2F2C4F; Thu, 3 Jul 2025 18:44:17 +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=1751568259; cv=none; b=H/kS751GIM4Gsm+BxiE9K1zXg5kDliRmXGf4HDFgYx9J9Qa0Mx8hDnVDVzF/BPZcqqfhuMtdgh+2r6cRABQqEgOkpiHJL0IUpdDuNq4WMYqHIa0g7VamEu3RBUaNWLW/kqqNp0HqaxJhEe/lq2PHl006lkanU7BvJ4UP1Ea9Uok= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751568259; c=relaxed/simple; bh=Q+6pd7cCvA5EXEoyvrOfENhFszYTXitZcBF7OVOVyWs=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=DuTu3lqEQXrt9w+RRSkEQf3q4xpSWFrFYGtc++alLbHbbjquYk92c13Eo0e1tcjN4UGt5226kJpV2HqmARAA/NISD7gn8dHn1q8J8SoiaZNo/YRtu2z6+JOjyL/2kTd6oyfK3EBU91dSUEWWt2nNE9o43mJSWzEx0wxzNLHnOZQ= 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=VUj8Ym7e; 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="VUj8Ym7e" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 3DD27406FA DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751568257; bh=OyvBF4RPZiy3zpxRyGPvRh4u0hkQVDBgNAz4FtBsEF4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=VUj8Ym7euDfk8aKDopNUkD9JuLWwr6GcvHI8PsNNYRJAqefPxpHMP/rqSOeVBHjxV KOX+sYM8ti2LX1gTva5TRg1icGPuGM76kOFiR9EcMnHY5dugbDAWqgijaoRmY+sd8b kAU+mBIzedjtRAbTRoiJTpHoujeCQ2PZCgldnBlnK2UH0I+Ii7lF23ue3vg3qxKDug 8DHzZSLyFEHlWTiZpokA/z5SzaEshhlDJXajR0MSvL5B1N6YcVmGoq21vIQSFt8zA3 h6Ukq2TpTmpTBCIbm5X3T3JuUE6qnwbh6HNLKU+roShjRitNgPhlfyLwOSiaNsGSs9 WhNtX5vbHqg+w== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 3DD27406FA; Thu, 3 Jul 2025 18:44:17 +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: some tweaks to process_proto_function() Date: Thu, 3 Jul 2025 12:44:01 -0600 Message-ID: <20250703184403.274408-6-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250703184403.274408-1-corbet@lwn.net> References: <20250703184403.274408-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" Add a set of comments to process_proto_function and reorganize the logic slightly; no functional change. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Tested-by: Akira Yokosawa --- scripts/lib/kdoc/kdoc_parser.py | 43 ++++++++++++++++++--------------- 1 file changed, 24 insertions(+), 19 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 61da297df623..d5ef3ce87438 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -1553,39 +1553,44 @@ class KernelDoc: """Ancillary routine to process a function prototype""" =20 # strip C99-style comments to end of line - r =3D KernRe(r"\/\/.*$", re.S) - line =3D r.sub('', line) - + line =3D KernRe(r"\/\/.*$", re.S).sub('', line) + # + # Soak up the line's worth of prototype text, stopping at { or ; i= f present. + # if KernRe(r'\s*#\s*define').match(line): self.entry.prototype =3D line - elif line.startswith('#'): - # Strip other macros like #ifdef/#ifndef/#endif/... - pass - else: + elif not line.startswith('#'): # skip other preprocessor stuff r =3D KernRe(r'([^\{]*)') if r.match(line): self.entry.prototype +=3D r.group(1) + " " - + # + # If we now have the whole prototype, clean it up and declare vict= ory. + # if '{' in line or ';' in line or KernRe(r'\s*#\s*define').match(li= ne): # strip comments and surrounding spaces - r =3D KernRe(r'/\*.*\*/') - self.entry.prototype =3D r.sub('', self.entry.prototype).strip= () - + self.entry.prototype =3D KernRe(r'/\*.*\*/').sub('', self.entr= y.prototype).strip() + # # Handle self.entry.prototypes for function pointers like: # int (*pcs_config)(struct foo) - + # by turning it into + # int pcs_config(struct foo) + # r =3D KernRe(r'^(\S+\s+)\(\s*\*(\S+)\)') self.entry.prototype =3D r.sub(r'\1\2', self.entry.prototype) - + # + # Handle special declaration syntaxes + # if 'SYSCALL_DEFINE' in self.entry.prototype: self.entry.prototype =3D self.syscall_munge(ln, self.entry.proto= type) - - r =3D KernRe(r'TRACE_EVENT|DEFINE_EVENT|DEFINE_SINGLE_EVENT') - if r.search(self.entry.prototype): - self.entry.prototype =3D self.tracepoint_munge(ln, - self.entry.pr= ototype) - + else: + r =3D KernRe(r'TRACE_EVENT|DEFINE_EVENT|DEFINE_SINGLE_EVEN= T') + if r.search(self.entry.prototype): + self.entry.prototype =3D self.tracepoint_munge(ln, + self.entr= y.prototype) + # + # ... and we're done + # self.dump_function(ln, self.entry.prototype) self.reset_state(ln) =20 --=20 2.49.0 From nobody Wed Oct 8 00:25:48 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 51C392F3642; Thu, 3 Jul 2025 18:44:18 +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=1751568260; cv=none; b=Ccve6kaZloZHFkloN0Sr11ZD5mAuq2tKqEfs22Y+A6NWU+cllRotyU90dB7eGr4ug3iqpiKVr3zsMzIgJd90mEcJjC4+h0QfP6O2uLJP8lFO0iwgWLMS87sxBKal/uOKobZcsTESnoSwVJ+4VMI5xnIKlwb77xvGg+blOKgniHE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751568260; c=relaxed/simple; bh=vAhak2IPVfCNWHFr7tDiv6SQZKJcEm/j+I4FBRxrSlo=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Cm2lvyYBnu9saLASIjTcFR6g6XnDjoQNr90S94EC0KzMt4ImoqN2ES9NX62HkHChBVcgCyZrIY1qrjfd4LxaZYMHUJdO7e1BEhbLQI4v9jNjq3HmtLMuiGUnaL7XPzCZfvCVA4iDr5cwn02ZLwzVIZImOgoBpwVZ/YbkhkZAprU= 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=VKAE+sGw; 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="VKAE+sGw" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net C38B340AC9 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751568258; bh=ddQFEymZ7aJoiSJ4Gc/pO4J4dh7GQJZLeL2BT7iTNl4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=VKAE+sGwU26/X8OFND9LHSYnnksvqaJU7dy70Jcgs4UYijD60zsEFUPAwzwMwJer5 l2TJWWXXhFYa5cTdW9DCaE0Sap/9hYQAJkiaHIpGbt2k1yNSANilNgNoz3xiuP5Wek KSL9DQ+fvjjjOqvzJkXULtzgzah9ApJb9zhX7+LaGUZtBkhAW1yophVDAJPODB3cq3 FBaS3nLXxSA7RsrGHCUj3QK3xaJQCmyX32CyToALKKp95nEC4l4Dsr0YDlkEaA7a/q FcI8aVmz5pI8YbbmMamxGOul0XfKnaZQ3mUNFxDXpI5CU9JsuQNiuiQ72pbUeLb3o0 uEgZZL7SQMqdA== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id C38B340AC9; Thu, 3 Jul 2025 18:44:17 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet , Jani Nikula Subject: [PATCH v2 6/7] docs: kdoc: Remove a Python 2 comment Date: Thu, 3 Jul 2025 12:44:02 -0600 Message-ID: <20250703184403.274408-7-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250703184403.274408-1-corbet@lwn.net> References: <20250703184403.274408-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" We no longer support Python 2 in the docs build chain at all, so we certainly do not need to admonish folks to keep this file working with it. Cc: Jani Nikula Reviewed-by: Mauro Carvalho Chehab Acked-by: Jani Nikula Signed-off-by: Jonathan Corbet Tested-by: Akira Yokosawa --- Documentation/sphinx/kerneldoc.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerne= ldoc.py index 51a2793dc8e2..2586b4d4e494 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -25,8 +25,6 @@ # Authors: # Jani Nikula # -# Please make sure this works on both python2 and python3. -# =20 import codecs import os --=20 2.49.0 From nobody Wed Oct 8 00:25:48 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 540E72F3643; Thu, 3 Jul 2025 18:44:19 +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=1751568260; cv=none; b=IrJAVEEw+pe6EA4+oJZynzgBbKhEb4R4cY4pZbvu8YHaoPOWSkYNUjGD8W4fIdXNTwU+I2mYnLyySR065x21d1YbGs+ovJSvqCKK3q+NgOB3rkhCcDnXF57Iuwz72c03hXOGa04sHPCSEF3qWwBIjgS9mwpLU5LOOiQBpY1tPG4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751568260; c=relaxed/simple; bh=IMZMFq5TKXw6E1r4xYMXLNJHbW8hgZDnfa5GM11GXWg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=A8rsbF2lEpMI2hpAWDL8EgTgUfGjFsIUGH5BVawIyfwqiOkG5myZox/3pfRlZlxWZv8VArRHHa/fx8Kocbh3get+jKvL4lnBONRBQs/WXScfGmxjMXEx/YK/4EiBvVHOBleAruIaaH0osh000y640EUQUHZkB0PG5s/d73sn+ag= 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=Syq7rXHs; 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="Syq7rXHs" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 67B5440ACB DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751568258; bh=YznuXaU2A2v6FfBG0rFTUZT8Xvml7SDQcFC8Z4GtlG0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Syq7rXHsAiWJFxhJDz1oLOOVxUArpCqXQ0zA9CVbCnzDLgxriT3hDEPGYdyj0+ISm 8ALDYuMiMSJdAgKJynx7Kmt8c8sPYQnsAQoCg/y/j+BLvTUogCJcrZio/e4UDiVjGe w1mFvcFA9RpRCGjR4YFRGZLsNBvYtChazH/SUiGBMfo/1gZuujWPEzSFltqaqPKPLK wmiWRn8hjG4LUeFLa/UhIXaR/rOMfhB13RfZREHbT1K7+x+96V7LEOgRs0DathVhUA YBN2IOWvswdrXVQ58oH0sCtXnImNfVOgI9FLSHyQi8JZeFJ3KVuJgevbhGGvBLo/+K vVVFwyHlwvxIA== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 67B5440ACB; Thu, 3 Jul 2025 18:44:18 +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: pretty up dump_enum() Date: Thu, 3 Jul 2025 12:44:03 -0600 Message-ID: <20250703184403.274408-8-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250703184403.274408-1-corbet@lwn.net> References: <20250703184403.274408-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" Add some comments to dump_enum to help the next person who has to figure out what it is actually doing. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Tested-by: Akira Yokosawa --- scripts/lib/kdoc/kdoc_parser.py | 39 +++++++++++++++++++++------------ 1 file changed, 25 insertions(+), 14 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index d5ef3ce87438..831f061f61b8 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -860,39 +860,48 @@ class KernelDoc: # Strip #define macros inside enums proto =3D KernRe(r'#\s*((define|ifdef|if)\s+|endif)[^;]*;', flags= =3Dre.S).sub('', proto) =20 - members =3D None - declaration_name =3D None - + # + # Parse out the name and members of the enum. Typedef form first. + # r =3D KernRe(r'typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;') if r.search(proto): declaration_name =3D r.group(2) members =3D r.group(1).rstrip() + # + # Failing that, look for a straight enum + # else: r =3D KernRe(r'enum\s+(\w*)\s*\{(.*)\}') if r.match(proto): declaration_name =3D r.group(1) members =3D r.group(2).rstrip() - - if not members: - self.emit_msg(ln, f"{proto}: error: Cannot parse enum!") - return - + # + # OK, this isn't going to work. + # + else: + self.emit_msg(ln, f"{proto}: error: Cannot parse enum!") + return + # + # Make sure we found what we were expecting. + # if self.entry.identifier !=3D declaration_name: if self.entry.identifier =3D=3D "": self.emit_msg(ln, f"{proto}: wrong kernel-doc identifier on pr= ototype") else: self.emit_msg(ln, - f"expecting prototype for enum {self.entry.i= dentifier}. Prototype was for enum {declaration_name} instead") + f"expecting prototype for enum {self.entry.i= dentifier}. " + f"Prototype was for enum {declaration_name} = instead") return =20 if not declaration_name: declaration_name =3D "(anonymous)" - + # + # Parse out the name of each enum member, and verify that we + # have a description for it. + # member_set =3D set() - - members =3D KernRe(r'\([^;]*?[\)]').sub('', members) - + members =3D KernRe(r'\([^;)]*\)').sub('', members) for arg in members.split(','): if not arg: continue @@ -903,7 +912,9 @@ class KernelDoc: self.emit_msg(ln, f"Enum value '{arg}' not described in enum '= {declaration_name}'") member_set.add(arg) - + # + # Ensure that every described member actually exists in the enum. + # for k in self.entry.parameterdescs: if k not in member_set: self.emit_msg(ln, --=20 2.49.0