From nobody Wed Oct 8 05:54:44 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 9179725CC64; Tue, 1 Jul 2025 20:57:57 +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=1751403479; cv=none; b=nUWx+fVNo0R4VavnXO+8TrlGO2QKXsVYmIrnrzipKqkQt8wkbk529CEkwSR6Z9ppkEZ69nF+XwgibxuN0diy35emb6xz12qXbvuWNoO7PdlIgbZyJ0fFaNE9wL+VB1/y6dhjk9DtkkuGzIbd2Y+aLtljrxWLA73Xhgh9pNIk0EA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751403479; c=relaxed/simple; bh=KYqOEOekJqwpYaqooxml5Dts4lbf4kZOWlZ+0aoxOvo=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=bBxVCJc4XEwW7DgkTJM85Zdti+fQrjnftuO05rafa46SdL1Dnf9eV2z0uIE0TPIbA1AgtW+zUjWmvUZk3rOg6thL3GqFqV+MoJFr8Onb3l9lIMw/7B9vqH86DX3+kKkzp2cEKnmSxTyrgpVaL7I4+PWxNiDh43l3/di6TvErzc0= 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=RW9QxO6h; 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="RW9QxO6h" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 355B940AAB DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751403471; bh=YS5GYF1vGlayogelwbv0AA+oVCbR+0CW7ssU1JVBYRE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=RW9QxO6hYz7qrib+tXEmwTIChgzRH1mAA42PqUCJ7O88iShaMZczyOM6CdtKcsM87 UD1Z8gBiagcfyax+soMfgILElpnt4mbFAfN3cLKeWj5dQ/x+tJeEc0DBrP/SOZbG8y Bg/MoAUohIIUnfoviKRkPiSSGRUyLAFCOdR+KQkNV3rrAxFWFkC8nJ4IIhlyDyKsBR FCmJZ9QwW9gdg9AAfExNW56DFY+sLykmm2uSOE4otM74avy0yECpC6gNCMa62DXYnn BOO4pcoHWZW0dMI7GeJ27IQmwKcVM04DORJa7AOS9StvcnBF5Y3BczJ2C1H25rt2eT 5Z8DMvlnM/8AQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 355B940AAB; Tue, 1 Jul 2025 20:57:51 +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: don't reinvent string.strip() Date: Tue, 1 Jul 2025 14:57:24 -0600 Message-ID: <20250701205730.146687-2-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250701205730.146687-1-corbet@lwn.net> References: <20250701205730.146687-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. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- 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 05:54:44 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 5CD25266560; Tue, 1 Jul 2025 20: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=1751403479; cv=none; b=Q1p1piSGDaN/qaXoFcgMJEevZImdDAJjgG4gZ+QRdKWGJ2MHmZWbwVPlTZJpb/PtIjyCwijqbUovw0XQzfwsEMDeldxS6hb+f/ipfHy3lsr6++awpdj/239szhzzylcXHu6OoONAgqooV5H7PxSVwHRx56KZpyn99WYddm7RU2E= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751403479; c=relaxed/simple; bh=Eaksr4HhPMjQmwPjPOOAjOOvNz7adjAjvNRO1mGvo5c=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=BanzwLeXIgzKPdTsqoOuLR1VJ+57wx22Y1r1QZHXGDOk50gWryvLZgPnbesXM9xeNaeUDAZDMzdETo6YTnhtnkOcfh/kScW67gB987GBcag3AqegWyrT/KmSVYPFU1j/HFuoNxKCppOzNgQ00ol0G99b4bdtP97x0RkfQJaDNT4= 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=IX7J0deq; 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="IX7J0deq" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net BF84540AD0 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751403472; bh=uKLzQw6LskeWU3LFVrkmzDlvEIcpVXbA+0YqM4MUzu8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=IX7J0deq62csjiUS+s4DmMe0Y9GFwQ0BurnEWF9KlHflSqAkYBwB2qw/txy/Uv+5n ji5jNokHj09mWoT+OvrWgvFT7p27TFcbf3kmMq6ll03wcYSCX72GJ1s7m9lmkSokn5 TMJCSYYEZOP5+BNV/UruaemBzmM+il/lvEXxwaIPP7TuEmXMHb1nI7XNzM//7V5vI0 CCJ8KOLZvv+Dc3O/xKrVqoY0eWOfCY2Q3bCNhnUIBCdxsN9ObRz3d3xl1dlkBcMldG 6diUfO7e1/2UU+2KktN8xOO3mK8ROzNgCDjw6nWSzlHEcIIWT4vje/YdCyvrLf2Ec7 qGSK17+FJrwoA== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id BF84540AD0; Tue, 1 Jul 2025 20:57:51 +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: micro-optimize KernRe Date: Tue, 1 Jul 2025 14:57:25 -0600 Message-ID: <20250701205730.146687-3-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250701205730.146687-1-corbet@lwn.net> References: <20250701205730.146687-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" Switch KernRe::add_regex() to a try..except block to avoid looking up each regex twice. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_re.py | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_re.py b/scripts/lib/kdoc/kdoc_re.py index e81695b273bf..a467cd2f160b 100644 --- a/scripts/lib/kdoc/kdoc_re.py +++ b/scripts/lib/kdoc/kdoc_re.py @@ -29,12 +29,10 @@ class KernRe: """ Adds a new regex or re-use it from the cache. """ - - if string in re_cache: + try: self.regex =3D re_cache[string] - else: + except KeyError: 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 05:54:44 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 5CD9228B3FD; Tue, 1 Jul 2025 20: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=1751403481; cv=none; b=Rf7JcOGdtqZKuQYH+/J+FewgTANsAiD+9mSAYo8JyX6OjpJjjIoMZ33jq5WEI5Amz/XF8bDjgo56eUQNvIURw/rqe6URYxtXf0lwvAYmsCAIzq/xiXkObY9IhvSBjN47VgV5b3XNPK2yHv38FK2chSQX7+iSC5JJvXHlnwSA2LE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751403481; c=relaxed/simple; bh=R3tNUtkVXW9CZKgkxhpPTYJhIbS0igKazDEJU749qP8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=jOBLlfeQoTRF2vB0wNcbWjOLzsBTsltaBgPjkbyPJ76SJaIl0zSG4zN10YJOJi+Qsh56Y81pWGd1PUBrSfNTqnEY2faUrYDjhYaaArsyYNJq2GVNMaAT28O+J1UqZNlr40+3PUPIT0JJoo+3x/Fa37PPz6KN3KFUVT23n3FQY9Y= 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=SZYedS01; 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="SZYedS01" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 5CE8840AD2 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751403472; bh=kBqglquqqrq2ldzkhbwrpnwof/hRu8OVVr4u0qu3yNU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=SZYedS015ASLKY9EUNU4z1ji9ODQ18DQ0BJl0ZOUJn2RCk7oFEIMyw+YIeVQLCrau OSOqpW2yJzIkB3YHgwtP9oP0RZozCSgPL4b3erG0AmH8jxrvm0AtQr5qOJisU74kbQ 9t1v3rxlpEKdPjRAeNZea54UuNeaKFa6YU8eNr2IJz/Haip/Crg7OoLzWay6NMWKQn oKi3xHEAK70o9ed/Nio5xmwp0jeOdV1f0qeC3qomWaOSlJUdM6kpqtCfwUiu0E4uuL JZ9MGf/Of0PJmRohi7fD63dmE9hGG/mg+ykfjmNEWvFoR7JwQ2nPPLeVOuzMOT7vU1 77cO58z0/bUaQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 5CE8840AD2; Tue, 1 Jul 2025 20:57:52 +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: remove the brcount floor in process_proto_type() Date: Tue, 1 Jul 2025 14:57:26 -0600 Message-ID: <20250701205730.146687-4-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250701205730.146687-1-corbet@lwn.net> References: <20250701205730.146687-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. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- 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 05:54:44 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 51ED6302053; Tue, 1 Jul 2025 20: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=1751403481; cv=none; b=sm9h49V9Qdsa3D0mt2Q9P7dnREGzwC2DkC9athgE9cHRBuquwh4go0bG7txa0oSUa7573k1m/Wz7SfsB1CxMxzB0x2dloDRt/3YU674Il5fdx1Av4F6NvjVp3cdBClPpx2uSo69+1EOW4sQ9TTEDqrX7RbeZxR6zic/HYOG+P2w= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751403481; c=relaxed/simple; bh=8woP62j53qGvsVZDuQRzXt2antcHS9ViJX/e9L82LsM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=sGdsvl+I2ei9LszQwB30zJxj3m00B8AIyhuT9P/AAWX3uJzD4v1uBeLn29ikcwB9wRO1ASzGQ+Un+z2MHb2aXT1X/KyzgQkrRZyxCTpiNf4eCI3c6xv7keakUtOFE/6tHLGNAu+BsV5a8GxbryWaU+QQUja1KRpCrTVrHWY36rk= 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=g7cchjSE; 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="g7cchjSE" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net E696340AD4 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751403473; bh=o/PYVZ1NQ2jZybUGo68fGCgKxKVLUxg0MJqImAONQxM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=g7cchjSELg7osNxKgpichOGBwO0niQOo/arzpU6CWUlrzPLEHZxUUcjDjNgVx7Rra UbWdlO2f6luNBbc/pcTRcmTRGwIZ8bsyLbe2LAa6wuFjcAs3YyYn2o6BrLXcEuye/W KkaHS6phJ/RnOCfP5kO+RZT3qtpbdmmOdxA9vM/dqM9R9itHzeGKtoTU73heQKoPaa CI2yONqSyS5vDqFwuYTII7B4Pr5iybh39wLov6/NmPixiaCs5Yo7UvZzZqGoPUfX40 EuvJlgsF8rgNWIGBKyPN4jWhISw0LR0aqNWw3SEIcIRf47BHBjLMq/vTBbpe9Zdpgj 2j+jw0GgPucvw== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id E696340AD4; Tue, 1 Jul 2025 20:57:52 +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: rework type prototype parsing Date: Tue, 1 Jul 2025 14:57:27 -0600 Message-ID: <20250701205730.146687-5-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250701205730.146687-1-corbet@lwn.net> References: <20250701205730.146687-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. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- 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 05:54:44 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 51E2A302052; Tue, 1 Jul 2025 20: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=1751403482; cv=none; b=fDUQSEUTDAKJSkH7dL8gaLOa1kW616s1AxRjMJCpB/EnlAIPris5DmL4MSqcNniURoDMQNHSQwOHq6yMIjyPtIAK7Z3ihvG8aIGLdXRXhNEnLP6+ae2gF4vJ7hH42cT9XQ09uLgIAzio/klPFv+zO+tAEmgERy9g7hUTLt7fEwg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751403482; c=relaxed/simple; bh=5DWm/6ZQ3Ik0vvHq5fw7kA4PUS5bPl9ddc1r9P6qLEw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=UClOyvU+nhx2FVGVB9E8JIrJHj2zWQdZUPLyh5fltsh27Csf5jEefbHOByUNkbMjRNyf6bV8SjiJqjBK+jJi7HNtSQX6+ZvDE6yQRqY5qRI0s160STe1YiFwyyMZn22UNjCRE30BgjhMwnxOHy+OEqdTQmhWfjU+Ud55VbtBXZ4= 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=GsMnbany; 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="GsMnbany" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 7578140AD5 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751403473; bh=IyKIcpsLSukks9lFrch8jdMKSN20+cjwdx2yLr/rmLs=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=GsMnbanySdfi6I0t+abPlJ3cC4pA891WZzMScXSPXi+GQB44/DtFOQ6OegiHVTE13 nXc8Uwp1HUKlW+08Yq9r+wQ+57PnCTFsmtKWc83l7uWbOQdOSD7SNyTrwueCyGg+Ht qn0SU1bmA2uAWq8I6apjDjrWiGfwSIBmveBI+8Hz5AcICSAHtnQ1VdesSwhCSod5Kv xMcbBU5LZbTD8+l6K8CzrVIBDut5iZL75hohzY4y3D4R6UF7Bqj64iLWk2Go67lMGY 5plmGPM7N9E7g6+d8O4KnllXjNR5Zzb0MKBWRxwu8fDn99B9CCMRBH1nbbQTf+w4Xb 4VqjrZ3DyQJmw== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 7578140AD5; Tue, 1 Jul 2025 20:57:53 +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: some tweaks to process_proto_function() Date: Tue, 1 Jul 2025 14:57:28 -0600 Message-ID: <20250701205730.146687-6-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250701205730.146687-1-corbet@lwn.net> References: <20250701205730.146687-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. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- 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 05:54:44 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 51DBB302051; Tue, 1 Jul 2025 20: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=1751403480; cv=none; b=BLADO9GI7SzLpcKjoMkLYzmZrSI8w4YqQOorfjWqxd2zywo/mkeRkOxi5ix2In8dE3oy+eYmqSASKO/DdgAqUUfGv/cFI2PxtnoRLwUjH51SB2hP9DxIvMWGCpVhpuXcKzTtPQ/0Scx9WxgIi+gGsfoQySMdUf9KGXzWiNXHqso= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751403480; c=relaxed/simple; bh=2uNWUnFz6VFj3YbuiVsJTLsLGYdeiVzhjNfgs8ldzqM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=k7IvCbN+dYX+0k0271NHNcecNx+eWyZYJvrH5A4UnJdDTiFe+b/DXIL6p3kT87aue7F1MQHgu130vkfjF97ClKUDSh5nwgAhHRL0IUHuHzcvnD4kXmkJOKOCsOGbNV+NTkQJP7M5gdLLnU0Wwu2E71DmA1jbN+4I/9UfF+aNbUQ= 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=ilk0K6r7; 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="ilk0K6r7" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 023AB40AD6 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751403474; bh=YaUJIiz2jpRN3BaARWqJEEaOxa+M9/8H2AtGoGu2KV4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ilk0K6r7pd9RnvOO11jgE8rhVhtW4W4tHloJFxkBitcoeiWMNrocD4oK0IPPF8iZo s4n2PfhvzrPDc/RvMZE6G7n0c9A/0+LHCYXUHiiFwj8OTNzUAnYykW+ZZuKaU6gSwD QjhH90hyAIkERwHFu5zDEf0cKy6NQj+iLm7yKcnNxwBc5JS6JGRxE03SWJUJ8ZZ1QW ZOzdlRMPN8uXCG0TjvT2xMhYdtoJQT6DGLfOCpxdG8knV3PWrVoX3bBOxu1ZLBX6lb UJr9u+nKazIM6pwb2Kb+6xdxsOOd3b8EP4Zz6AvEM76oQ5GMX0E+Dogq/PnquqEscM +2wGOD20UuMKw== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 023AB40AD6; Tue, 1 Jul 2025 20:57:53 +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 6/7] docs: kdoc: Remove a Python 2 comment Date: Tue, 1 Jul 2025 14:57:29 -0600 Message-ID: <20250701205730.146687-7-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250701205730.146687-1-corbet@lwn.net> References: <20250701205730.146687-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 Signed-off-by: Jonathan Corbet Acked-by: Jani Nikula Reviewed-by: Mauro Carvalho Chehab --- 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 05:54:44 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 8E39F30205E; Tue, 1 Jul 2025 20: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=1751403480; cv=none; b=tunFXxew9DBNmAO4bSrrqJac+kVX7O0Tm8/aK+KRRvhM9KSyxU7/wkTsnJFF4JMHUYrsGH4ndi++QZ/jV0v9/2LiHEHMt1+c+qPaPfJell6ZdAbG9qNd6n7iG+D0wh25GQ9pF8iFDsLv62AKxg2wzbK4KGn9ajjVZiAhRSP2Vgg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751403480; c=relaxed/simple; bh=hdpGtK68M+XvvOVPSZyN4HZX2pXXmSiwJyQ18ETu3nI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=HkziUQq7vavFdzIrcGe/2OyK1MV+3Ib5RnX0f9cAfeuRrjEALEonQzLTBVn9N3skS1mTQ2XcR09ReltbJjQHjx2Et48aODYJvP3BrvzkD5Z0cm6PAEdNWzrD0/4QkIe9qfrz13bV9xd+A4YhoV/hV/5bVqEU+Ohwgg0EtfCJtEU= 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=s6JvMXDL; 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="s6JvMXDL" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 9963640AD8 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751403474; bh=TgRHmnD9p/dcTjvHMT/O3rjBTcvebrZIoBEnST2G+eA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=s6JvMXDLKphB81ffbri4jUyYW+0wVO+BNDqKLFdSrpS9dcflyzCA9/yexj9yzRicu YX97yJHC20rKbYRrk9Ia9t3qi/JECcgCbNEtUINxSIVMvs+oZEB0U5SjLa5IZIXfuz ZdcTy1em6hOVB6KcUeWF6E5Rro4BjQIfAk+3G9Ldb47g6UUUlCd4LzzIALnNAtMxgl 4DDQ4uVeeR6Ix8rmqckY2Be1GndvtQzJtNZlZqMwfNsGGgQo2Iugxrkw6HCjaPclfQ EjmlLTFVRTXaDbfpw247V2Kcdja0+PCW/apora88+gty0ExG5Tq+RSR7WWndqLezOK 5UmehBkje5h0Q== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 9963640AD8; Tue, 1 Jul 2025 20:57:54 +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: pretty up dump_enum() Date: Tue, 1 Jul 2025 14:57:30 -0600 Message-ID: <20250701205730.146687-8-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250701205730.146687-1-corbet@lwn.net> References: <20250701205730.146687-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. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- 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..50e25cf62863 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