From nobody Thu Oct 2 22:53:07 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 64E76322C81; Tue, 9 Sep 2025 20:44:07 +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=1757450648; cv=none; b=DobZ0HFEgxZFJskmijzwOSE3zlmSUkKIFaeeb2Wd83c8WxVE/3VVeO3gU9DJxzQcu/9ns+vdh0ZZ+QoWThcx5QYEc9zKj1cZ4ij1BK7Lzml4Fs4xIgU5rHFwPStrX1vNv8ZVyapQrI68N4fX6sJh7yX1TPhl17+TTbXqX3Iu2Dw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1757450648; c=relaxed/simple; bh=RsUW04hskqugOhbYYrFUMf4gRDhS4v7kPG2OtwRduZ4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=cau7QYAHZnxXo+BRVNfFEAQtn80a794t3jERZroDPxLk0YhITw/+j7ONXUibGa6bMD/QEqC0r4WidDnxpt95LZkW+xFFodG4LG/G8uK3lcb9/ox+xX78h0ZW/sae4bgdv3CbLKyXMm01JFI+aXgQHBS3y+BYmzGMsM3y7jm7d2s= 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=Nek8+z1i; 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="Nek8+z1i" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 59A7340AF9 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1757450646; bh=JfEtJEANLxItI8g8VENMIRoKiFMhUsfKRtczZcQaItw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Nek8+z1iTAEhQZlS5a+RuHXD14rVdS3GDzl11k502VNue7Ic+9rYA61a/EiEyglwp Yf4oZpJU2OYYq92NcJwTiQAD6QlKJhU34Y5kuJ3MssmAZwjEiEhcxbKVGqYQQo2IY8 W3hBskEoDHQIaDX871Kg57QjiTzfols3h+0//HXwmpUi658cO61JzDNJ4sGpQpRoak EfswpHXHmWWjwkrgQBJHizkrjQkrLg+apqCGqXb0Uj8ieQWjqmUPynsw3HWFsMdZLY Omw5wt2xiXxEPHqqHL+sDNUZHGdWiMurJarJm1hKN5hj9fwEcbM37CEwWZR0Cwjl1K jnuytE6ZL4qBw== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 59A7340AF9; Tue, 9 Sep 2025 20:44:06 +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 01/13] docs: kdoc: trim __cacheline_group_* with the other annotations Date: Tue, 9 Sep 2025 14:43:37 -0600 Message-ID: <20250909204349.123680-2-corbet@lwn.net> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20250909204349.123680-1-corbet@lwn.net> References: <20250909204349.123680-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 special case for __cacheline_group_begin/end() can be handled by just adding another pattern to the struct_prefixes, eliminating the need for a special case in push_parameter(). One change is that these annotations no longer appear in the rendered output, just like all the other annotations that we clean out. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index a560546c1867..a90f77d6b669 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -90,6 +90,7 @@ struct_prefixes =3D [ (KernRe(r'\s*CRYPTO_MINALIGN_ATTR', re.S), ' '), (KernRe(r'\s*____cacheline_aligned_in_smp', re.S), ' '), (KernRe(r'\s*____cacheline_aligned', re.S), ' '), + (KernRe(r'\s*__cacheline_group_(begin|end)\([^\)]+\);'), ''), # # Unwrap struct_group macros based on this definition: # __struct_group(TAG, NAME, ATTRS, MEMBERS...) @@ -447,12 +448,6 @@ class KernelDoc: self.entry.parameterdescs[param] =3D "anonymous\n" self.entry.anon_struct_union =3D True =20 - # Handle cache group enforcing variables: they do not need - # to be described in header files - elif "__cacheline_group" in param: - # Ignore __cacheline_group_begin and __cacheline_group_end - return - # Warn if parameter has no description # (but ignore ones starting with # as these are not parameters # but inline preprocessor statements) --=20 2.51.0 From nobody Thu Oct 2 22:53:07 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 BB452350D79; Tue, 9 Sep 2025 20:44:07 +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=1757450649; cv=none; b=q4BfYi8T1WkBlO+q3GXsof+zv72ZNHrj8y3tyLKxFekw0R6pG+sNGd7vt1WwrxD+n2ECREXUkiZxwrgzp8eCtuijbX5S/urWQwZCXhl/V6AzYXjsj/YtW99QDnaeMPG41D3RTJzWGjiE6Hdb6xUu485i2ZXT5eDx8+UnfbP1QAU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1757450649; c=relaxed/simple; bh=SFo3P+DFPQ/PbtARAg0L61NmxcdgAaF5r71CrGjFQLw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Fa+TmOIUwlYLEnFTXY3RUj3Gx/SHex5O8WvCxtDNBn5itrJJK1BfOPqR2S3EsqOcGgMgVFBXrh2vGXc858WWtAqJkvnxph+nU6zxI8l7Q1XkPg7QaX1v2IGTyldSGVwjxOZcB3NVS0W+XyFkVZl4to8Kr0yqYaNwSo7qNORveSs= 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=Ps5b0S0u; 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="Ps5b0S0u" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net D6A9240B0A DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1757450647; bh=rDpxipI8EI5OEDh5p749/x1weU3Phuf2YfP4ttB8VO4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Ps5b0S0uBIfuXkU3GkwZiRn57a0m9kRolwbpKaAoSK8vHJBysyld3IugS/t1z1nH1 CdEZrEqVmXhgEAXPU3Qi6++1qUcPMaY0Nqrrz8R9ZNzMedit40+Pc/dEdZV5joWJ8t VV7gwZWEs122xvLMEyyqjGMeo+PPs4+9SpYf4X+tiZODSiSJrBUa9D3aU5Kio1QZIN 4Y5Bf82LLQOLgODBURuXYV/o+rKLeOXa+S1yfk/orEl+BN8VyT06BOeKrVtDJjEaGI 9qnrJrXuyZ3YlwLb7aVfIdmocNvUxrk7S07oVk/pbLUhRWJ581u6LcYYXrTvVO3CJU 3MCFvl3WyBk6Q== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id D6A9240B0A; Tue, 9 Sep 2025 20:44:06 +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 02/13] docs: kdoc: tighten up the push_parameter() no-type case Date: Tue, 9 Sep 2025 14:43:38 -0600 Message-ID: <20250909204349.123680-3-corbet@lwn.net> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20250909204349.123680-1-corbet@lwn.net> References: <20250909204349.123680-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 handling of untyped parameters involved a number of redundant tests; restructure the code to remove them and be more compact. No output changes. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 44 +++++++++++++++------------------ 1 file changed, 20 insertions(+), 24 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index a90f77d6b669..2118c20b3056 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -423,30 +423,26 @@ class KernelDoc: =20 param =3D KernRe(r'[\[\)].*').sub('', param, count=3D1) =20 - if dtype =3D=3D "" and param.endswith("..."): - if KernRe(r'\w\.\.\.$').search(param): - # For named variable parameters of the form `x...`, - # remove the dots - param =3D param[:-3] - else: - # Handles unnamed variable parameters - param =3D "..." - - if param not in self.entry.parameterdescs or \ - not self.entry.parameterdescs[param]: - - self.entry.parameterdescs[param] =3D "variable arguments" - - elif dtype =3D=3D "" and (not param or param =3D=3D "void"): - param =3D "void" - self.entry.parameterdescs[param] =3D "no arguments" - - elif dtype =3D=3D "" and param in ["struct", "union"]: - # Handle unnamed (anonymous) union or struct - dtype =3D param - param =3D "{unnamed_" + param + "}" - self.entry.parameterdescs[param] =3D "anonymous\n" - self.entry.anon_struct_union =3D True + # + # Look at various "anonymous type" cases. + # + if dtype =3D=3D '': + if param.endswith("..."): + if len(param) > 3: # there is a name provided, use that + param =3D param[:-3] + if not self.entry.parameterdescs.get(param): + self.entry.parameterdescs[param] =3D "variable argumen= ts" + + elif (not param) or param =3D=3D "void": + param =3D "void" + self.entry.parameterdescs[param] =3D "no arguments" + + elif param in ["struct", "union"]: + # Handle unnamed (anonymous) union or struct + dtype =3D param + param =3D "{unnamed_" + param + "}" + self.entry.parameterdescs[param] =3D "anonymous\n" + self.entry.anon_struct_union =3D True =20 # Warn if parameter has no description # (but ignore ones starting with # as these are not parameters --=20 2.51.0 From nobody Thu Oct 2 22:53:07 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 658A0352FD0; Tue, 9 Sep 2025 20:44:08 +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=1757450649; cv=none; b=mR7GdFR+UX26stM5GG0aAVgqAG16t++A0aSrKiwsa8WUOop6XPJEtaMgkFPU/EzFCGrc6CBr/WNivGGl4Z8b+ZriDGPHEzpEZJSmDia/AuvUnQTNs73ZW5FsxUdJW9nhaOeU1QCSWRJEqmx6+Mt3WghFXKnst056X4aFi45rpAY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1757450649; c=relaxed/simple; bh=rEctjVEMrcusVAKt6bJpmB6kpl+NhauZEayBdQUhQ/g=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=U3RmKWJ/V99+8whqP+0ensokmfPFSEKMl5QFBABfZxSH2h6w9dFel6iUOCMFhdjX7i1B6CEWkUmAB3C4wQWkY+tmC16Nus8xoELM7+uuxFXYjWIen6EqOxgiVUiudXU9FDfvi6lY1280xpPa/+xKAs2VDVXcPUCh6Tl4Kg5WWHM= 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=HRg+rZIF; 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="HRg+rZIF" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 60C1740B0B DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1757450647; bh=BGqHXiew3PPntdhvPFvwS+m9Yv4GGGGtHEvQoh2kNvI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=HRg+rZIF2jxUUXheNxM5uk8UwPlucCyR6tR5rMvVi+0mkpr+mbLWbpPjuL1doRYpA No+4BuFyCv+jn2K+LhAqvj66B77TZZEOfG45r8uFRMOIMFRR2savf5iIclr6hLSwe0 LZu1R1lGkV7Ri33RQlwwrSfQPqmAiA70/QjdQE9Dp94Th3WMNzUduE0RIGGBod0pxf P4b6X20aCto0HzAxR+feP8icGiKek2y6jekyXHdsg0ofc1FBUwIk44s6Emepj7Zvd4 UfZbm611DEhIloaslNJ8U/+waCr8+OriUOlMuN/ZKxuUmaN08FmRtb9WEBcajz4SQL QTU7agCAeB0SQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 60C1740B0B; Tue, 9 Sep 2025 20:44:07 +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 03/13] docs: kdoc: remove a single-use variable Date: Tue, 9 Sep 2025 14:43:39 -0600 Message-ID: <20250909204349.123680-4-corbet@lwn.net> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20250909204349.123680-1-corbet@lwn.net> References: <20250909204349.123680-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" struct_attribute is only used once, so just put its value there directly and drop the name. Signed-off-by: Jonathan Corbet --- 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 2118c20b3056..b25c8d80b965 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -76,13 +76,11 @@ doc_begin_func =3D KernRe(str(doc_com) + # initial " = * ' # Here begins a long set of transformations to turn structure member prefi= xes # and macro invocations into something we can parse and generate kdoc for. # -struct_attribute =3D KernRe(r"__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)", - flags=3Dre.I | re.S, cache=3DFalse) struct_args_pattern =3D r'([^,)]+)' =20 struct_prefixes =3D [ # Strip attributes - (struct_attribute, ' '), + (KernRe(r"__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)", flags=3Dre.I |= re.S, cache=3DFalse), ' '), (KernRe(r'\s*__aligned\s*\([^;]*\)', re.S), ' '), (KernRe(r'\s*__counted_by\s*\([^;]*\)', re.S), ' '), (KernRe(r'\s*__counted_by_(le|be)\s*\([^;]*\)', re.S), ' '), --=20 2.51.0 From nobody Thu Oct 2 22:53:07 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 D21963570DE; Tue, 9 Sep 2025 20:44:08 +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=1757450650; cv=none; b=WEGSkQUpcMvDZrWg7LdKHsK1RzLCcEpqszZrlPDWblzyqi72vcZSd5U4StJ6ziACWImDkXb6HYtrZWMHRnXy+nLIfhB1uH8TurKsYF8KzFac1OKSCC3Nwbh+6eP9iiMu0OJnSz9awJKtLaePc0Yh32ZYvpxyPv4neRTqeWRlfH4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1757450650; c=relaxed/simple; bh=dVnTN1ZB9rHPPAewB8+4/hp3Yefxvz9mJGdD6N6SVug=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=XgmrPS020pKPGhQFx8LvQPnvl75yk+/nWq/DcmfY4XcMm112Q70YdNxkiTHKI6RENqr00puEN1CYgH6VYjRlSEUQNXBwPyz97WsNREFQqO3YeZqicz4hn/GhWv2BUJD4cidKOJ5X4GV1SjTcap6oej/a42dcWzrjJG2OayLiT84= 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=LQ6qP+qV; 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="LQ6qP+qV" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net E929040B0D DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1757450648; bh=sM6yLOmeT9VY//fAZZjmTl/NENsjERpuU/z8WGNUlX0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=LQ6qP+qVfIbSYkiF0OaPwO5KNComZUR/Ijspw5tPp7L6EWMPb5GPzLgKQEyH0aJWh QUi7d/tesaKFAIVf7LURUNAWu/VTzwpjvBpKxjiSr718HGp1WDBESKcvrZ8H5idSJE atcUzkxqBqBlIqDvS71ibv43Z6i44WrlV77VAzc+F+UcAC+6Whh414Rj8uOA6mWJ0K iqtaPDpczEW3QsN7ioSI81/SOWjUEN8Ia0KhDBgdgRNEwsX5lv3MOGupt246/Us+BB ZMNMoD+yIcToVBmKK2ex1k2WJyFCRzXvKz0Ix6AlS5gEz4crY63Y2VbYSoNPm9jhIX uaRoOrcpvItfw== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id E929040B0D; Tue, 9 Sep 2025 20:44:07 +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 04/13] docs: kdoc: move the function transform patterns out of dump_function() Date: Tue, 9 Sep 2025 14:43:40 -0600 Message-ID: <20250909204349.123680-5-corbet@lwn.net> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20250909204349.123680-1-corbet@lwn.net> References: <20250909204349.123680-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" Move these definitions to file level, where they are executed once, and don't clutter the function itself. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 78 +++++++++++++++------------------ 1 file changed, 35 insertions(+), 43 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index b25c8d80b965..37811cddd55c 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -161,6 +161,37 @@ struct_nested_prefixes =3D [ (re.compile(r'\bSTRUCT_GROUP\('), r'\1'), ] =20 +# +# Transforms for function prototypes +# +function_xforms =3D [ + (r"^static +", "", 0), + (r"^extern +", "", 0), + (r"^asmlinkage +", "", 0), + (r"^inline +", "", 0), + (r"^__inline__ +", "", 0), + (r"^__inline +", "", 0), + (r"^__always_inline +", "", 0), + (r"^noinline +", "", 0), + (r"^__FORTIFY_INLINE +", "", 0), + (r"__init +", "", 0), + (r"__init_or_module +", "", 0), + (r"__deprecated +", "", 0), + (r"__flatten +", "", 0), + (r"__meminit +", "", 0), + (r"__must_check +", "", 0), + (r"__weak +", "", 0), + (r"__sched +", "", 0), + (r"_noprof", "", 0), + (r"__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +", "", 0), + (r"__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +", "", 0), + (r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +", "", 0), + (r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)", r"\1, \2", 0), + (r"__attribute_const__ +", "", 0), + (r"__attribute__\s*\(\((?:[\w\s]+(?:\([^)]*\))?\s*,?)+\)\)\s+", "", 0), +] + + =20 # # A little helper to get rid of excess white space @@ -894,49 +925,10 @@ class KernelDoc: return_type =3D '' decl_type =3D 'function' =20 - # Prefixes that would be removed - sub_prefixes =3D [ - (r"^static +", "", 0), - (r"^extern +", "", 0), - (r"^asmlinkage +", "", 0), - (r"^inline +", "", 0), - (r"^__inline__ +", "", 0), - (r"^__inline +", "", 0), - (r"^__always_inline +", "", 0), - (r"^noinline +", "", 0), - (r"^__FORTIFY_INLINE +", "", 0), - (r"__init +", "", 0), - (r"__init_or_module +", "", 0), - (r"__deprecated +", "", 0), - (r"__flatten +", "", 0), - (r"__meminit +", "", 0), - (r"__must_check +", "", 0), - (r"__weak +", "", 0), - (r"__sched +", "", 0), - (r"_noprof", "", 0), - (r"__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +", "", 0), - (r"__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +", "", = 0), - (r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +", "", 0), - (r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)", r"\1, \2= ", 0), - (r"__attribute_const__ +", "", 0), - - # It seems that Python support for re.X is broken: - # At least for me (Python 3.13), this didn't work -# (r""" -# __attribute__\s*\(\( -# (?: -# [\w\s]+ # attribute name -# (?:\([^)]*\))? # attribute arguments -# \s*,? # optional comma at the end -# )+ -# \)\)\s+ -# """, "", re.X), - - # So, remove whitespaces and comments from it - (r"__attribute__\s*\(\((?:[\w\s]+(?:\([^)]*\))?\s*,?)+\)\)\s+"= , "", 0), - ] - - for search, sub, flags in sub_prefixes: + # + # Apply the initial transformations. + # + for search, sub, flags in function_xforms: prototype =3D KernRe(search, flags).sub(sub, prototype) =20 # Macros are a special case, as they change the prototype format --=20 2.51.0 From nobody Thu Oct 2 22:53:07 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 20A1F35CEAC; Tue, 9 Sep 2025 20:44:09 +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=1757450650; cv=none; b=GO6U5634Fq5ATzypSqOhvPfPqGMkm3TKfl0i7wQjHcw1InGNNzHk+UitS7rCgUfCQoDAV631DJPVK/2vzxnFFPtknkyDoEEI5tXVrSErlgr1L6ML9r+tJS6dt8jouliH3uFFrTMxlUcgqv7XB7oePKMeVQtcTfblzP62lD7GIzg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1757450650; c=relaxed/simple; bh=8coTWkl2AD9BkrxfhklAw1gUBG+qTo7VVyeQr2YqZKA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Jj3Ro0NVbk4V07Y9U1jDiznuiHokhl4Aidwi+Ff+13M8XIdJT8o82wtEblTLgRBGoWXFE5vidsjyAKRTTsq8iF+Gf/8/GQQD+sckvrxyaIWT9D23piVQlamUuMqnoR6qzQxCwKbjd3YPoHpk+bqeUHxFXTabQSoHzOuXV1eGqTU= 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=SFvkvOdf; 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="SFvkvOdf" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 76BC440B0E DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1757450648; bh=sWYJLRDobwyVmZeD8KxFPOinWqMDBv8Qm6wdf5j2Djc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=SFvkvOdf+m3mAWC77VKDK6Nss1wHfFsKtLXMY5jY36fuLUG8Gg71gH+8RI3Bo1G7b Vz6IX9QHgWMgkEv06nuUfT/P+jLxbhecSdc4NGgABDBE46n2GdezLNtMkoGT3K5YCZ YrYn5nkdH+ImLKxGeU/MNKKUWEsMvM9cCe7PpM0+sjKtLXwnYAPFxl3VMdsCB/GLVy ZWBpdD6WKGfaiMDAvVL+I72u5gd/ZiScyRNjT5Py+taMdkpW7j0lxdnnaaAuOZlXhg b89bUgPGcG3bMsCxXtw00/zp4uM2/Bcg5HfcA8Ss8NO31aEI3Y3Tc89kZOEQp96gTH xggveqxuO9lXA== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 76BC440B0E; Tue, 9 Sep 2025 20:44:08 +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 05/13] doc: kdoc: unify transform handling Date: Tue, 9 Sep 2025 14:43:41 -0600 Message-ID: <20250909204349.123680-6-corbet@lwn.net> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20250909204349.123680-1-corbet@lwn.net> References: <20250909204349.123680-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" Both functions and structs are passed through a set of regex-based transforms, but the two were structured differently, despite being the same thing. Create a utility function to apply transformations and use it in both cases. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 65 +++++++++++++++++---------------- 1 file changed, 34 insertions(+), 31 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 37811cddd55c..1a1558211acd 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -78,7 +78,7 @@ doc_begin_func =3D KernRe(str(doc_com) + # initial " * ' # struct_args_pattern =3D r'([^,)]+)' =20 -struct_prefixes =3D [ +struct_xforms =3D [ # Strip attributes (KernRe(r"__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)", flags=3Dre.I |= re.S, cache=3DFalse), ' '), (KernRe(r'\s*__aligned\s*\([^;]*\)', re.S), ' '), @@ -165,33 +165,39 @@ struct_nested_prefixes =3D [ # Transforms for function prototypes # function_xforms =3D [ - (r"^static +", "", 0), - (r"^extern +", "", 0), - (r"^asmlinkage +", "", 0), - (r"^inline +", "", 0), - (r"^__inline__ +", "", 0), - (r"^__inline +", "", 0), - (r"^__always_inline +", "", 0), - (r"^noinline +", "", 0), - (r"^__FORTIFY_INLINE +", "", 0), - (r"__init +", "", 0), - (r"__init_or_module +", "", 0), - (r"__deprecated +", "", 0), - (r"__flatten +", "", 0), - (r"__meminit +", "", 0), - (r"__must_check +", "", 0), - (r"__weak +", "", 0), - (r"__sched +", "", 0), - (r"_noprof", "", 0), - (r"__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +", "", 0), - (r"__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +", "", 0), - (r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +", "", 0), - (r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)", r"\1, \2", 0), - (r"__attribute_const__ +", "", 0), - (r"__attribute__\s*\(\((?:[\w\s]+(?:\([^)]*\))?\s*,?)+\)\)\s+", "", 0), + (KernRe(r"^static +"), ""), + (KernRe(r"^extern +"), ""), + (KernRe(r"^asmlinkage +"), ""), + (KernRe(r"^inline +"), ""), + (KernRe(r"^__inline__ +"), ""), + (KernRe(r"^__inline +"), ""), + (KernRe(r"^__always_inline +"), ""), + (KernRe(r"^noinline +"), ""), + (KernRe(r"^__FORTIFY_INLINE +"), ""), + (KernRe(r"__init +"), ""), + (KernRe(r"__init_or_module +"), ""), + (KernRe(r"__deprecated +"), ""), + (KernRe(r"__flatten +"), ""), + (KernRe(r"__meminit +"), ""), + (KernRe(r"__must_check +"), ""), + (KernRe(r"__weak +"), ""), + (KernRe(r"__sched +"), ""), + (KernRe(r"_noprof"), ""), + (KernRe(r"__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +"), ""), + (KernRe(r"__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +"), ""), + (KernRe(r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +"), ""), + (KernRe(r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)"), r"\1, \2= "), + (KernRe(r"__attribute_const__ +"), ""), + (KernRe(r"__attribute__\s*\(\((?:[\w\s]+(?:\([^)]*\))?\s*,?)+\)\)\s+")= , ""), ] =20 - +# +# Apply a set of transforms to a block of text. +# +def apply_transforms(xforms, text): + for search, subst in xforms: + text =3D search.sub(subst, text) + return text =20 # # A little helper to get rid of excess white space @@ -807,8 +813,7 @@ class KernelDoc: # Go through the list of members applying all of our transformatio= ns. # members =3D trim_private_members(members) - for search, sub in struct_prefixes: - members =3D search.sub(sub, members) + members =3D apply_transforms(struct_xforms, members) =20 nested =3D NestedMatch() for search, sub in struct_nested_prefixes: @@ -924,12 +929,10 @@ class KernelDoc: func_macro =3D False return_type =3D '' decl_type =3D 'function' - # # Apply the initial transformations. # - for search, sub, flags in function_xforms: - prototype =3D KernRe(search, flags).sub(sub, prototype) + prototype =3D apply_transforms(function_xforms, prototype) =20 # Macros are a special case, as they change the prototype format new_proto =3D KernRe(r"^#\s*define\s+").sub("", prototype) --=20 2.51.0 From nobody Thu Oct 2 22:53:07 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 04F9D35E4FF; Tue, 9 Sep 2025 20:44:09 +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=1757450651; cv=none; b=A8qskq7jwrMEwAOttn89FBvsf3B4sN9b2PCZTxi1g7JJpZGeEsLc7qXf9ROh8TguhhHFEE3STwz9MmkCDJjSUck3OmVHYSAYQs9rSlyjSQvaBMgS+OFJ/YH2QEqevQkvjROzrqLZYgeRXg/Hl+n00EZaD7i72waofPFbh7CW+AU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1757450651; c=relaxed/simple; bh=1Hil1T0T3/8TdBDvQViio/0LTRVCyBM2IZXgP69Suag=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=EEn0TofgWWMjoqex+DvT2bP3YvvTlA2X0gVctMX4NGyOCo1Sq0WkaDHfBUMIR/d9PUN/WZaUjKC5mu5xxEtgD0UeszeXj3ELwJFgJls2CjS0cyOC8G73p3HPmXZfBFAReQZjCSUhfffKVzyzeKk9yXMsVzY35nARS81vAQHUJx0= 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=YKHaoV5z; 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="YKHaoV5z" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 037B440AF5 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1757450649; bh=h98HvVjpkeDQfU+Z0XxLLWseUleTkvErmLg3KT4Sv3Q=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=YKHaoV5zv+NVH8W34z7YSJ2KTUNAYG+PWI8tlilJJ25h+RA2b8pFdBJODRNTjdbbb tER42/Sr3TBDbVGrwecuF2BpgSV8Xf5Wje0sYWtbgEtSAgd1ZAHQsFrfc+fyVfCOFg q2Q48zWmEaPVKZlZp1n3INfvWXuWRvK+k16bit/zjHwg9oyk0gpCWyDPQuJeH7hipY wU3IEea+ifcLAenG34mSGca04iXvCQOBFZFbconxOu9E4PA5yPgLNyqcw2aiQNa+/e KwxpNDbKItF/5IEnFK/1oH86WwKayYcUodqYs4kF/aICjtr/bS8B52DoytC7En8TsQ jxPCgoUmItzhg== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 037B440AF5; Tue, 9 Sep 2025 20:44:08 +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 06/13] docs: kdoc: remove a couple of spurious regex characters Date: Tue, 9 Sep 2025 14:43:42 -0600 Message-ID: <20250909204349.123680-7-corbet@lwn.net> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20250909204349.123680-1-corbet@lwn.net> References: <20250909204349.123680-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 "name" regex in dump_function() includes both the tilde and colon characters, but neither has any place in function prototypes. Remove the characters, after which the regex simplifies to "\w+" No output changes. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 1a1558211acd..decd127df82e 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -958,7 +958,7 @@ class KernelDoc: # - atomic_set (macro) # - pci_match_device, __copy_to_user (long return type) =20 - name =3D r'[a-zA-Z0-9_~:]+' + name =3D r'\w+' prototype_end1 =3D r'[^\(]*' prototype_end2 =3D r'[^\{]*' prototype_end =3D fr'\(({prototype_end1}|{prototype_end2})\)' --=20 2.51.0 From nobody Thu Oct 2 22:53:07 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 7F241362065; Tue, 9 Sep 2025 20:44:10 +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=1757450651; cv=none; b=ILCA1vbLeTCcXQ80HoUo6Nds9Ftq87GuJ8itydPwDUErsWIl1wVxVopOZzpntt2Aehqk6zCOY0K5a7BSIkh/FDNsFT4v2l9wBC54R/wfC/MfFtf+fD5w2obZiSV0dyZqiYv731GMzi9sVuWpk+6Qfx7ig4u4TUpxEB56oZAbhac= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1757450651; c=relaxed/simple; bh=zUbK1eRvQNBcMGzevTG6U8Mg+cORrqJFgihTfL+HD/c=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=mV5kz9t9Kzw3XhSfh/gZXXzFyQ+pTPk3C4bU39JExQ+Gw0WJAYNIbTpacXoEGuXVwgU88sE9f1TkeAeN4rluLz7zqx/gzQ3t1ddhkMEPpYILDcisvAQ8du4ymAmKzc7L5vDZCLXGlxLKoAjVEfQc/zMFdF6vYu2RRAN4A8pwdWo= 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=JX4gfELN; 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="JX4gfELN" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 8E33540AF9 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1757450649; bh=mx/+MAve9gRBP77jA9qbgrPKmVOV176WxvHPdldB/Jo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=JX4gfELN3ozI9r9A1SfhiWbP3ILvz0ODqCPECh2advPluTWnENNK3sPP2C7yk+OFN /BngFmxLe3GH4zyERQ7RGWjTf9L9ShKKOQE1U9YtGVB8ynLquZnSfc8iZJbAWTrKwx 8vlOvPoRuwquJ0y7/tZ1V9hVOo5HdAdxiU+yJP0n29a+raOB+5fHYZ3D7neuWGLNb1 TmH5w1CfzZzgvbc66nXSruXxrdz1GP2cEeXlm224i3vbCQO1pkrZ5J2hFYMhOOx+8/ 21Pt/BIp5rneQmIbJbFhQOIBxjslpM2iQtEpZbSVwCb1JGkMukTJNvAcr6wCQREbEv XcsiKl5S9fMHg== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 8E33540AF9; Tue, 9 Sep 2025 20:44:09 +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 07/13] docs: kdoc: remove a useless empty capture group Date: Tue, 9 Sep 2025 14:43:43 -0600 Message-ID: <20250909204349.123680-8-corbet@lwn.net> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20250909204349.123680-1-corbet@lwn.net> References: <20250909204349.123680-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 is_define_proto case in dump_function() uses a regex with an empty capture group - () - that has no use; just take it out. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index decd127df82e..f9be5414244d 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -972,11 +972,11 @@ class KernelDoc: found =3D False =20 if is_define_proto: - r =3D KernRe(r'^()(' + name + r')\s+') + r =3D KernRe(r'^(' + name + r')\s+') =20 if r.search(prototype): return_type =3D '' - declaration_name =3D r.group(2) + declaration_name =3D r.group(1) func_macro =3D True =20 found =3D True --=20 2.51.0 From nobody Thu Oct 2 22:53:07 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 F0614362086; Tue, 9 Sep 2025 20:44:10 +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=1757450652; cv=none; b=Gs7Id/Cwxmpzxckh5l/iALSKCY5/xKVgsJ0iWvmE2LOGpy8fv3qjluZp89Y9YGD5bb2jm2iF7/eLtoUwlGsDJakYOrTRKX0ru/MHQ13ahFVC5Mq9k9Y/vGdvhNksnadAd7RZzuCDUtOUY4qRQ1MvJBEqfb2J41gcz6lecGAS5F8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1757450652; c=relaxed/simple; bh=Pbi97irdb+l3J3vafjWQ+be7jYpu3PYYTrbjHKpYHO8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=OrqsHg/NbN+EgoqN75BCliXqK9Xa1S5R9M3wBbAXIvqRa9k/Va7K0JqCpBlmcXQDG0aZ4kqnNH7wqfk+ChnlyLWjpJrHNZ4Nn4PPN8oAtwE2OyEsJG98NYRqNVQy6ZiusjPFDfFkasWG1T+RjlZSXdDy1foxGjHz2/M1b+7Jx9k= 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=YKcO3g1D; 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="YKcO3g1D" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 22FBA40B0A DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1757450650; bh=hgUN8fgcYskEUVklIECVzi6lK3ek6ekWW59of72+uww=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=YKcO3g1DgUm9nQUuhWN30ENfXQah4k0j9mFkpzgHNpCLYWcW4DIcZCSRTkgbk8ugi x4MPcDm3/fJsKGCBtw1qEU8WtzOwjKCn08aTECYPlgA2aG6/auCGIXiUYciRSINOAg pUwSlgYepyCito34ScDEYsJSHLYIcTkSQn+aaYgUXrsi840Qz7nscslS6hY6kUDFma YeM9SfWrTCPLzgr3wmQoXGZd9tUbXQMKSG1UppZsWAA+qqF0BdLZ1JKe6Sdw0ImYcg NZtp5daZrnMdYWJ8X8uzPbFi1c/wSM13Dm+uL5DFpbYrhgjPZ/EZZPZkaHPAsK3mkl QUfDMDLP3aP1w== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 22FBA40B0A; Tue, 9 Sep 2025 20:44:10 +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 08/13] docs: kdoc: Simplify the dump_function() prototype regexes Date: Tue, 9 Sep 2025 14:43:44 -0600 Message-ID: <20250909204349.123680-9-corbet@lwn.net> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20250909204349.123680-1-corbet@lwn.net> References: <20250909204349.123680-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 regexes for the parsing of function prototypes were more complicated than they needed to be and difficult to understand -- at least, I spent a fair amount of time bashing my head against them. Simplify them, and add some documentation comments as well. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index f9be5414244d..ec2e6e83df05 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -959,15 +959,15 @@ class KernelDoc: # - pci_match_device, __copy_to_user (long return type) =20 name =3D r'\w+' - prototype_end1 =3D r'[^\(]*' - prototype_end2 =3D r'[^\{]*' - prototype_end =3D fr'\(({prototype_end1}|{prototype_end2})\)' - - # Besides compiling, Perl qr{[\w\s]+} works as a non-capturing gro= up. - # So, this needs to be mapped in Python with (?:...)? or (?:...)+ - type1 =3D r'(?:[\w\s]+)?' type2 =3D r'(?:[\w\s]+\*+)+' + # + # Attempt to match first on (args) with no internal parentheses; t= his + # lets us easily filter out __acquires() and other post-args stuff= . If + # that fails, just grab the rest of the line to the last closing + # parenthesis. + # + proto_args =3D r'\(([^\(]*|.*)\)' =20 found =3D False =20 @@ -983,9 +983,9 @@ class KernelDoc: =20 if not found: patterns =3D [ - rf'^()({name})\s*{prototype_end}', - rf'^({type1})\s+({name})\s*{prototype_end}', - rf'^({type2})\s*({name})\s*{prototype_end}', + rf'^()({name})\s*{proto_args}', + rf'^({type1})\s+({name})\s*{proto_args}', + rf'^({type2})\s*({name})\s*{proto_args}', ] =20 for p in patterns: --=20 2.51.0 From nobody Thu Oct 2 22:53:07 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 51A1A362982; Tue, 9 Sep 2025 20:44:11 +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=1757450652; cv=none; b=T4tF0XvmFEUsVUJicm35v2MxnrF5AvqsJbqDIeFDzPvhs+mZ6djoBTaCMYxkJtUHBU1XxivV5SC8uC+uVyEvY+8WPI/DbTX+dOMi6XMuVvoCK+5AqjIVsILKZ9h+sBiJXf1PdACJAvWcy6qLzu1cGlXP/5Ak+MiTgSOn+nPBDb4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1757450652; c=relaxed/simple; bh=UUikvXhoU1n+d3L3fH+HOOxaLxdRorEDbrqgyrx1PLM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=BJj1NAD0rGYAM3Z1Gme3sjHOm5YY+lk73+yVlEZ3tcuno9jxRKeIeb1jrv3ninfaWwjroLT801dUprs1Fcgh8EfJcwuA5yEo7j9QY2yA0t6/eG04Ic71D5ktuOedCfkeBLWQLYkGFEjgavLWfFV4ABtD0Ebhpvp29bPEXmYW+1Y= 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=iHPPZP2R; 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="iHPPZP2R" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net A3A7140B0B DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1757450651; bh=FuBMOOv3BTXg/gSEWq2cWSKAA57PetmUukt7C50G6AA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=iHPPZP2Ri6n0pYwd/kUQReM9eAhzgzEUjdl+JTpbgCJZqK4GF+r319w3eCYMBSeSa JCSQ3hiuLiZulETdm7QTu0JYArMqX8FZwQkcPlim6lZIkXBB5LQNkEjZTOdfxZa+6p GeYEtYDhHeiaQ9lZ5NI14gE9dh2Z0V6d+fNYuu43tld01YJ1FeaSVYs6KPK55JIFrk XqHGXuvEFYfb9hVmcy76/yuHx3m06RltdUX3Aa2OjwIygY5WVqpr7rr/Cxqj4l/7tp DjJ4TlGuanH33RAUVu7uCpKc91qn6EqfrnkfoNrWfk2aV+5hKHkJK6/fXMkE6yU3A9 KocdoX3HO4hHw== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id A3A7140B0B; Tue, 9 Sep 2025 20:44:10 +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 09/13] docs: kdoc: consolidate some of the macro-processing logic Date: Tue, 9 Sep 2025 14:43:45 -0600 Message-ID: <20250909204349.123680-10-corbet@lwn.net> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20250909204349.123680-1-corbet@lwn.net> References: <20250909204349.123680-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 to handle macros is split in dump_function(); bring it all together into a single place and add a comment saying what's going on. Remove the unneeded is_define_proto variable, and tighten up the code a bit. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 43 +++++++++++++++------------------ 1 file changed, 20 insertions(+), 23 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index ec2e6e83df05..27329ce9b5e9 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -926,21 +926,31 @@ class KernelDoc: Stores a function of function macro inside self.entries array. """ =20 - func_macro =3D False + found =3D func_macro =3D False return_type =3D '' decl_type =3D 'function' # # Apply the initial transformations. # prototype =3D apply_transforms(function_xforms, prototype) - - # Macros are a special case, as they change the prototype format + # + # If we have a macro, remove the "#define" at the front. + # new_proto =3D KernRe(r"^#\s*define\s+").sub("", prototype) if new_proto !=3D prototype: - is_define_proto =3D True prototype =3D new_proto - else: - is_define_proto =3D False + # + # Dispense with the simple "#define A B" case here; the key + # is the space after the name of the symbol being defined. + # NOTE that the seemingly misnamed "func_macro" indicates a + # macro *without* arguments. + # + r =3D KernRe(r'^(\w+)\s+') + if r.search(prototype): + return_type =3D '' + declaration_name =3D r.group(1) + func_macro =3D True + found =3D True =20 # Yes, this truly is vile. We are looking for: # 1. Return type (may be nothing if we're looking at a macro) @@ -968,19 +978,10 @@ class KernelDoc: # parenthesis. # proto_args =3D r'\(([^\(]*|.*)\)' - - found =3D False - - if is_define_proto: - r =3D KernRe(r'^(' + name + r')\s+') - - if r.search(prototype): - return_type =3D '' - declaration_name =3D r.group(1) - func_macro =3D True - - found =3D True - + # + # (Except for the simple macro case) attempt to split up the proto= type + # in the various ways we understand. + # if not found: patterns =3D [ rf'^()({name})\s*{proto_args}', @@ -990,16 +991,12 @@ class KernelDoc: =20 for p in patterns: r =3D KernRe(p) - if r.match(prototype): - return_type =3D r.group(1) declaration_name =3D r.group(2) args =3D r.group(3) - self.create_parameter_list(ln, decl_type, args, ',', declaration_name) - found =3D True break if not found: --=20 2.51.0 From nobody Thu Oct 2 22:53:07 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 CF1243629BF; Tue, 9 Sep 2025 20:44:11 +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=1757450653; cv=none; b=qfFWDYEFJ/al7Q7AdRKK4Zy0CPrfe2hAIDURWszP47Q+CdXxjexG2vMbTRAeo5keIrQE7cWmTjL96g0JIgAl6OnUPpCKQ3e1B3BjwtcFGSm68N29d6iyv6RekEGhRubw/7YpIUH9RpLe7q4zX9ada5ID1DO/yTPPpS3uN2jE6x4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1757450653; c=relaxed/simple; bh=AskytDTPrYtPcFGtBEg3Nbq7tOIZzlhLCwApIormsQI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Ps/HNsySB8L4srtbeLJ9JH+AB+GSoxBrhBNT8fvb1EeLC8rNfck5n1AiEK4qfc5SyRF06Lu95sfJr6czbQFLk4o2zqlPOcl0i3KPnk3VD5ohBjRYhDwZTVTfykr89R1BP9YXigSqVZOU5VfV3sLGzcXEvvKkDL8sVgT8PDyMktc= 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=FYDTe1UG; 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="FYDTe1UG" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 2E61840B0D DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1757450651; bh=zUk5SRpzBj/HzKwulzlMEnnF5K8QVNxzFjyZknCsUzk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=FYDTe1UGMhK3JgTKPiSNEMSUu2O3kCurzo8+nug0kYljIrwmEZL5g0SFzUTYRCy0H 2+IH3B1CGyiEooXkeRmnmCV1KVwr+j6XuuATfJUHNiZu7K3u988BFzxwvQMT3lerVd VpfRuqH19JLPY7PP9rXG3BFIQYIMnojREWp6J5yxZ11yafXvp2M4DIkxbmqA34BY5p oJahEfSltaYrDXCZDRkEVwrLbzmVne/IoNOOXoPzIhpfkkvgmlzK5cbPrgQE9mKBFZ ke4P1jFdUbLvOV6l+zKU1bAUhw2RTUBcrKasb3V+lBXfyUJy3zrNiUXJk9nzXSK9Cj 92iYXB3cV+wAw== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 2E61840B0D; Tue, 9 Sep 2025 20:44:11 +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 10/13] docs: kdoc: final dump_function() cleanups Date: Tue, 9 Sep 2025 14:43:46 -0600 Message-ID: <20250909204349.123680-11-corbet@lwn.net> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20250909204349.123680-1-corbet@lwn.net> References: <20250909204349.123680-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 more comments to dump_function(), add some comments, and trim out an unneeded duplicate output_declaration() call. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 30 +++++++++++++----------------- 1 file changed, 13 insertions(+), 17 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 27329ce9b5e9..5e41acfef7b8 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -999,32 +999,28 @@ class KernelDoc: declaration_name) found =3D True break + # + # Parsing done; make sure that things are as we expect. + # if not found: self.emit_msg(ln, f"cannot understand function prototype: '{protot= ype}'") return - if self.entry.identifier !=3D declaration_name: - self.emit_msg(ln, - f"expecting prototype for {self.entry.identifier= }(). Prototype was for {declaration_name}() instead") + self.emit_msg(ln, f"expecting prototype for {self.entry.identi= fier}(). " + f"Prototype was for {declaration_name}() instead= ") return - self.check_sections(ln, declaration_name, "function") - self.check_return_section(ln, declaration_name, return_type) + # + # Store the result. + # + self.output_declaration(decl_type, declaration_name, + typedef=3D('typedef' in return_type), + functiontype=3Dreturn_type, + purpose=3Dself.entry.declaration_purpose, + func_macro=3Dfunc_macro) =20 - if 'typedef' in return_type: - self.output_declaration(decl_type, declaration_name, - typedef=3DTrue, - functiontype=3Dreturn_type, - purpose=3Dself.entry.declaration_purpo= se, - func_macro=3Dfunc_macro) - else: - self.output_declaration(decl_type, declaration_name, - typedef=3DFalse, - functiontype=3Dreturn_type, - purpose=3Dself.entry.declaration_purpo= se, - func_macro=3Dfunc_macro) =20 def dump_typedef(self, ln, proto): """ --=20 2.51.0 From nobody Thu Oct 2 22:53:07 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 90045369341; Tue, 9 Sep 2025 20:44:12 +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=1757450654; cv=none; b=aexCwl/5E7bg8kbKDpRxZacYlukJs+ixO6MbDG5zDndxM8twsXyWaVwQ+tmDY9jjVK3pK3KDPFD07t+UDjYTex3LyusK86DEEzYAKmhxrwcntxlNf0UjHksrWSbJNf7ED0bPOAxfgLCDbzsqOzM41RveI3FAq1HVmxbfuhSWWBE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1757450654; c=relaxed/simple; bh=5jYxorbLgCEpYTieVLb99AISkxmhC85Kru2W56AqpFw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=hrfyJu5BZPCTdRZFLAlYYTL8uuJbW9hbqkQQpnd/cT6LxO4ntTBIDNuYTe6Bi3bnYz+ulQbv3gtimyWlotFNhqtrEsRh4J9iJkcIpH/mhirz4CgxUOjvEe6bt3oxALrBNwr1z66jut2rVkbZe6SsSeSds1Pz5QjCN8yHMPY11Rc= 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=ErrT+I+W; 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="ErrT+I+W" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net AD57E40AF5 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1757450652; bh=9kn0Au9AyM4/U2zNWSXOAZeKscoX0rDzipkOnd9Uri4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ErrT+I+WIL20KD3e//Ww1AIuTT1ydccMVlYr/iUVPR7MGDLKKrYGq0mzNghWsYVAM ZTsHjuDS4FBRbIUH33GhveETW8ynJyY8sKe1sxB4g4MBYMC7UozHo16nx1YipLlyd1 AmHJX0mlJ5pBRUidWd8r0SMRz1QT02ZDwLkQjnVIZi9sJ2WS+XcsVdpWoDXEvIOsaF Sq0RP/v2SOL+cG1C9GxzmKdvPzTkrWwGLJoU4Fiu2i4E2lK8M8mHKbWEU1/2Kq38HW /Ibj1bWvdYL3GMYhGofPYg3JoKfwCBX0Wg2GRiJVtFxE9SJ+X1Sh1+sdH0JtFbd5Cj cT7lOfaN1UgsQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id AD57E40AF5; Tue, 9 Sep 2025 20:44:11 +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 11/13] docs: kdoc: remove some dead code in dump_typedef() Date: Tue, 9 Sep 2025 14:43:47 -0600 Message-ID: <20250909204349.123680-12-corbet@lwn.net> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20250909204349.123680-1-corbet@lwn.net> References: <20250909204349.123680-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 regex in this block of code makes no sense, and a quick test shows that it never matches anything; simply delete the code. No output changes. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 5 ----- 1 file changed, 5 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 5e41acfef7b8..7c739b495d58 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -1060,11 +1060,6 @@ class KernelDoc: purpose=3Dself.entry.declaration_purpo= se) return =20 - # Handle nested parentheses or brackets - r =3D KernRe(r'(\(*.\)\s*|\[*.\]\s*);$') - while r.search(proto): - proto =3D r.sub('', proto) - # Parse simple typedefs r =3D KernRe(r'typedef.*\s+(\w+)\s*;') if r.match(proto): --=20 2.51.0 From nobody Thu Oct 2 22:53:07 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 38C15369996; Tue, 9 Sep 2025 20:44:12 +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=1757450654; cv=none; b=KVXyqdSEchYOPWtfs7O+xnXfdzQl3tS65MIVgGA80OrQ4p/2k8wI8ySOcaA94575Rxhn573MVWNCAYZJ7nlPKmZe9UYD4AcwNQsApMFiFP+63ZI9P7qj+O6Xr06SaFOuBqSBR8FkhysRaQ0XN2kvFa9Wk+lduo/zCx7iZ7zkyJY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1757450654; c=relaxed/simple; bh=7S5dUGAfJGWm8b/CJhy4nJzu5ZjFZu1HP4LLrFgDvUg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=bN0Y+3PdDPkeTB/oMBgdrwEVNBNEJmzY90EPlrM8pX0j39+lG1vSfB4BhrbtP/fs34UcLfBrAYGkTZDaqEFfnytRwmwy2OElYgv7SbJhWvaNVdHK8fdaXZ8yGw3SpcBo3lrb6HQd80UopE64mSIx9P0HJgP+DYofAKzAeU6cbCE= 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=FWLdzBuL; 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="FWLdzBuL" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 43E4E40AF9 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1757450652; bh=1ifSUfKnsb0QBGqZsGY9eFnpqWQlv1CiBS0YMJAWZlE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=FWLdzBuL5JSgOlDHTv8fTvqIlFccx1sUkwd3zytWRl/8pJObeYNakFkNrxCmmZKE1 DOLZTseQAjyZyJ2y4Sx3P3Y6zBn5v9Vyaa3LAVNz7II8hzPT70z6NnTJZCFn5+qp9v 2yhuu15bPn99dyKWXokfZAxPGO8N7ODtDIqXXRKak8dQzyzw86dfTC/ZO4glM/g8Ns t52+MZiBOJDy87yCH/KUIcfj1BXXLGlNm5eeGRCOqug/ZIFfebOi4aslgqDQxHTwYg ObyzpCjeUxi/KCk2WTcUu44tazXWEf2OnMUfgFrfZ0qp075AY2bMU1k5SlKwegHqii GlhbMN0xnQ3GA== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 43E4E40AF9; Tue, 9 Sep 2025 20:44:12 +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 12/13] docs: kdoc: remove redundant comment stripping in dump_typedef() Date: Tue, 9 Sep 2025 14:43:48 -0600 Message-ID: <20250909204349.123680-13-corbet@lwn.net> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20250909204349.123680-1-corbet@lwn.net> References: <20250909204349.123680-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 we get here, comments have long since been stripped out; there is no need to do it again. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 7c739b495d58..ad9df0536bbf 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -1034,9 +1034,6 @@ class KernelDoc: typedef1 =3D KernRe(r'typedef' + typedef_type + r'\(' + typedef_id= ent + r'\)' + typedef_args) typedef2 =3D KernRe(r'typedef' + typedef_type + typedef_ident + ty= pedef_args) =20 - # Strip comments - proto =3D KernRe(r'/\*.*?\*/', flags=3Dre.S).sub('', proto) - # Parse function typedef prototypes for r in [typedef1, typedef2]: if not r.match(proto): --=20 2.51.0 From nobody Thu Oct 2 22:53:07 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 793EF36C069; Tue, 9 Sep 2025 20:44:13 +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=1757450655; cv=none; b=a8D9kho4Kh90HVH/yVb3jyngDqwtwotfboGcTbDvhjqLDKY3Q+InD7yEm9h/Srb2UJaa5o+yZS+B9E5tu7vPifGPFpHfwyRc7GTdziMSSbqgi9uW8ZkZ/kqkTOHn67GSZlwbT4Djl3ILQ+b1NkLwif2Buf1BT5KLjBWCajng+KA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1757450655; c=relaxed/simple; bh=NMocIPZH9YYVlYA4WELxtNVYiL1e4gKHtr7tQenrv4A=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=diOtomOL+f7NjTybU2lJcttVyLq9AEC4OlFd13jI97LWuAH/hyWLo6K2fmZvQVgqa/4s300vi5gerOaPsvxsNdLJvcA/mxI95qZOcOVQJaBxm2UUrA7Me+0vPLIPf2fN/hqdOjm9owISfioSlb7p50TT4H/1yeBC+vWRarqQbOk= 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=XYHmQAjw; 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="XYHmQAjw" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net CBD3B40B0A DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1757450653; bh=hBEi+Apqy84zf44aihUNbWI24oug2rNRLrGTbbRP7Dc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=XYHmQAjwL4G9TmRkRFLn87fPqkxQRM88ByOmFfPoxivzGTGCZGSqPCriDiXHJH8h0 vzZv80QmmSImn/fxVtpm3qOTY+8pI5Di/IkruFjuCCibltxsvesD1UsmVHtIA8duZX ZNC47z6N4mR2jDd4HAmRJWS9rUfCeVw0qm0Jgp79CPdIESp9gvR/O4HyKblKF4D/9J tLyruu6A4yjJjNV6BXSR7bgl9s11p5l5kwBDRdRfKGoAC4ylA2EUtv6CZZvWU2A915 w1kW77RHHYZfURqw1ZaVR4/P1o5+tX4OtRmkJ7G5QIFWsbbFLgigpgJ9eO9mlHtR0x eK/wmhuQYfsXA== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id CBD3B40B0A; Tue, 9 Sep 2025 20:44:12 +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 13/13] docs: kdoc: a few more dump_typedef() tweaks Date: Tue, 9 Sep 2025 14:43:49 -0600 Message-ID: <20250909204349.123680-14-corbet@lwn.net> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20250909204349.123680-1-corbet@lwn.net> References: <20250909204349.123680-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" Merge "typedef" into the typedef_type pattern rather than repeating it later, and add some comments. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index ad9df0536bbf..8215948dd548 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -1026,13 +1026,15 @@ class KernelDoc: """ Stores a typedef inside self.entries array. """ - - typedef_type =3D r'((?:\s+[\w*]+\b){0,7}\s+(?:\w+\b|\*+))\s*' + # + # We start by looking for function typedefs. + # + typedef_type =3D r'typedef((?:\s+[\w*]+\b){0,7}\s+(?:\w+\b|\*+))\s= *' typedef_ident =3D r'\*?\s*(\w\S+)\s*' typedef_args =3D r'\s*\((.*)\);' =20 - typedef1 =3D KernRe(r'typedef' + typedef_type + r'\(' + typedef_id= ent + r'\)' + typedef_args) - typedef2 =3D KernRe(r'typedef' + typedef_type + typedef_ident + ty= pedef_args) + typedef1 =3D KernRe(typedef_type + r'\(' + typedef_ident + r'\)' += typedef_args) + typedef2 =3D KernRe(typedef_type + typedef_ident + typedef_args) =20 # Parse function typedef prototypes for r in [typedef1, typedef2]: @@ -1048,16 +1050,16 @@ class KernelDoc: f"expecting prototype for typedef {self.entr= y.identifier}. Prototype was for typedef {declaration_name} instead\n") return =20 - decl_type =3D 'function' - self.create_parameter_list(ln, decl_type, args, ',', declarati= on_name) + self.create_parameter_list(ln, 'function',_type, args, ',', de= claration_name) =20 - self.output_declaration(decl_type, declaration_name, + self.output_declaration('function', declaration_name, typedef=3DTrue, functiontype=3Dreturn_type, purpose=3Dself.entry.declaration_purpo= se) return - - # Parse simple typedefs + # + # Not a function, try to parse a simple typedef. + # r =3D KernRe(r'typedef.*\s+(\w+)\s*;') if r.match(proto): declaration_name =3D r.group(1) --=20 2.51.0