From nobody Sat Feb 7 06:55:19 2026 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 6B680289343; Fri, 6 Jun 2025 16:35:02 +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=1749227703; cv=none; b=Kluyq8eoQnppgyJ5DBejW1oalQ4CB8ZOrZceyUBcjjZIjv+vJuuyvwBeREaNekHV25KoNOD1OJkP/awmCsUeMKM6vOVSHFk5RvTCmiWdU2b0rbVfTGfsYt9H7t28Hjw1Glwc16rkHzjNzG0lr/MMorWQTi0tCXeXCPlyU+U8Gs4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749227703; c=relaxed/simple; bh=bL+QHcqwfC8ABcx3C+jB5ggAUwlz3u+lLoepArUuyr4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Yo4F3uCn47wWSVYYE2kqld12rq50SdEDgihZ1LqZD/y1vNslLDwv+JuPRA51xT2w/VmzzwlRiT6V82tOVzCtNSDls2+ziskW9fWzdoLcOUI8gFS4a1Sy156T+myNTVGana0xeAc6ZiHEXWx1GgNWmoYgQXVVkvFctJRqnjqerK4= 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=lOUPmEcW; 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="lOUPmEcW" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 8478C41ED3 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1749227695; bh=+15mNl+MASymclHrVaWDQ75LDqc61Li1JLr+euAhV24=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=lOUPmEcWCQEs9XtmJTi62N9JYKvRGyvOhnwfBVclXwE9jajDW6fvFbJZ3AQ/Cgfyd vL6Dobi4PO61+cncfNiqNiKnGG2uCoEEsZ22vphdbx+rMf+3lPTByUY2eO1XG5d7fj PjKPH9Z4XtDay8y06HZWa/3KyW/7CAlAhpjm8D0reoXweUIQIS3WrGWOzDOQ9KJ/Jc IBeKI4Z+ZUw20n2//CzIqxYGSHxMT66oe2q7yVeVLcFrj3TnrP+Afn9Rfdx6HpywAD WbMos8f6NdHZxQnjAf0YXoZCbjMsW3YMIlJU9R5U9CykNU4AcF0m3L6ESSwyaZrfVb SaVOB67FvzHRg== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 8478C41ED3; Fri, 6 Jun 2025 16:34:55 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Jonathan Corbet Subject: [PATCH 1/9] docs: kdoc: simplify the PROTO continuation logic Date: Fri, 6 Jun 2025 10:34:30 -0600 Message-ID: <20250606163438.229916-2-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250606163438.229916-1-corbet@lwn.net> References: <20250606163438.229916-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Remove the unneeded "cont" variable and tighten up the code slightly. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- 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 062453eefc7a..b193cf9dc0d1 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -1680,7 +1680,6 @@ class KernelDoc: Besides parsing kernel-doc tags, it also parses export symbols. """ =20 - cont =3D False prev =3D "" prev_ln =3D None export_table =3D set() @@ -1696,18 +1695,14 @@ class KernelDoc: if self.state =3D=3D state.PROTO: if line.endswith("\\"): prev +=3D line.rstrip("\\") - cont =3D True - if not prev_ln: prev_ln =3D ln - continue =20 - if cont: + if prev: ln =3D prev_ln line =3D prev + line prev =3D "" - cont =3D False prev_ln =3D None =20 self.config.log.debug("%d %s%s: %s", --=20 2.49.0 From nobody Sat Feb 7 06:55:19 2026 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 6B60E2853F6; Fri, 6 Jun 2025 16:35:02 +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=1749227705; cv=none; b=sboC7ubwH2OIZrZXejwoyhS3xOsKmroRRmuGJ9PXqJq01TgsvQYDko5UbLoSX6ePTfxzQb7SVWm85QSN9it4fPxEP/vYLIXB/yUFSNhq681dlwxVLRtv3QZGzAVhSjrnakHE4StdxEJs9zk25Gu69GmT5YZbAr2U8dTsSEFI+tY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749227705; c=relaxed/simple; bh=Xk9ajLZGYrjC8GxOtF2H673cXwx3Vc4L5ZswNgZDV3w=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=CdAVBbzxqu1EcdiuAhmFuVMIGNlYbfzTzRNcUHzvfT6cOA98mugXNqeguRXhuwjLYN0ge00xhbMxDmVGAV2WyVvNWXXkn0hWwnJLyyeIkw4mlFKWDHfkheYB9/G3pTk47IbQEHrNKeI1eWf25XFHFQ5rQ/QkhshtPj5rjngMoKg= 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=H1xF6vEh; 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="H1xF6vEh" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 1433541F26 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1749227696; bh=k4wWLzw3KH5+stcNScMYwU5UgcBq+X0OjHCe0oISl2s=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=H1xF6vEhKkve9MVXtJu94HsbQIumFIoSU2FEcFb5iXjDA00SutPir3hSzpQ6ZeRrz 535yNLQZSTBMCqiJ2/cWmea/zXQWVIV2hSu7A4Q3UJvYKq/UW3zur2Z/Mh5V3OzFXs 04pihMcrB1Ha15T41MbLf76NNeQMPxrPc0QxKf8VBdbwdL09SYw12xbXMK0GVfhhDI dKJv6s22LQPyqnfbQy1LTW5WEtpbhESv+9EfUh5ZujGrFKC0QwoEMDlc9mgasj8+gJ kMd70nrQ1mvtz1RQspFSLiNknjSoOzkrY0QiTZCN4+KaRX+X0NtUzJyeGtbmelvjSC 2jobPetci4UIw== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 1433541F26; Fri, 6 Jun 2025 16:34:56 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Jonathan Corbet Subject: [PATCH 2/9] docs: kdoc: move the core dispatch into a state table Date: Fri, 6 Jun 2025 10:34:31 -0600 Message-ID: <20250606163438.229916-3-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250606163438.229916-1-corbet@lwn.net> References: <20250606163438.229916-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" Since all of the handlers already nicely have the same prototype, put them into a table and call them from there and take out the extended if-then-else series. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index b193cf9dc0d1..37b7e501af7c 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -1670,6 +1670,21 @@ class KernelDoc: =20 return export_table =20 + # + # The state/action table telling us which function to invoke in + # each state. + # + state_actions =3D { + state.NORMAL: process_normal, + state.NAME: process_name, + state.BODY: process_body, + state.BODY_MAYBE: process_body, + state.BODY_WITH_BLANK_LINE: process_body, + state.INLINE: process_inline, + state.PROTO: process_proto, + state.DOCBLOCK: process_docblock, + } + def parse_kdoc(self): """ Open and process each line of a C source file. @@ -1721,19 +1736,8 @@ class KernelDoc: self.process_export(export_table, line) =20 # Hand this line to the appropriate state handler - if self.state =3D=3D state.NORMAL: - self.process_normal(ln, line) - elif self.state =3D=3D state.NAME: - self.process_name(ln, line) - elif self.state in [state.BODY, state.BODY_MAYBE, - state.BODY_WITH_BLANK_LINE]: - self.process_body(ln, line) - elif self.state =3D=3D state.INLINE: # scanning for i= nline parameters - self.process_inline(ln, line) - elif self.state =3D=3D state.PROTO: - self.process_proto(ln, line) - elif self.state =3D=3D state.DOCBLOCK: - self.process_docblock(ln, line) + self.state_actions[self.state](self, ln, line) + except OSError: self.config.log.error(f"Error: Cannot open file {self.fname}") =20 --=20 2.49.0 From nobody Sat Feb 7 06:55:19 2026 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 93063289E0E; Fri, 6 Jun 2025 16:35:03 +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=1749227704; cv=none; b=EUdvgeGI4HIWZi+wZqbJIg+K5Lwl/1ozxGkumpPexfiYKiBgroeoEvHBYX+39KoqsBcZQ7LMW8+PNw27PFf532VxNSmCG+XbPUxdr+kXLJRDtNY6WjIJVuwJMhUHoNnYDhs9xG8PwIHllmRdzDII0li7B4baBkyLvL2sWYBNR3Q= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749227704; c=relaxed/simple; bh=cCX7+iWaJ32ve9qQ3KC+4mD5gRO5zvHS+vb0szaj5U4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=okUfA3PsDm0WEbKoJPNbY7Syl4yeJWIrIrKdxOMMR7EZph2c01C7HOLBNLWBg2JDZT9jG6QD12FFi1Q2hvOkq2eP61aDSoRcn0Jnk2Hezan0P/2WyZT9xbz0piJz255CDPy3XLnkQjHR0uYTJlb2O+hxGgOfoMOZkGfrKCpOW2E= 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=mQp/ZkYO; 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="mQp/ZkYO" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 8B01241F2D DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1749227696; bh=kb0zYT2ntM43Di/wACcwU37EP9pm+N3CV36LcbfUc8o=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=mQp/ZkYOFsY7Xqy23HT/R20g7ZE6o9KfI5D9i3+6GwtAi0u69hCaPW+iWKbw/54IW duHvkF01168QoqMNYFeWHI/DbkFlTWY5v+p80SjuCM6DXeJoLIW3D9mxveAE5XTbx/ nZqMFLF1VPcYoRV5J4Lxmd1n8OxcPFjCbiOsyJslwq//W71k/4EVSuGiGHs3U0y8Yn 2hey/30Au39GNuuSwTYniINs1AvDlxPXNbwdKSEWFjAU3vUxddWIFOqzSAVAGdk10A n0as7RGCel3jb+AqHhdggCqD4jIaGdZwD7f6zCTpufa4namzhgpIY3l/1SYbHxnu7y xb1kCnanpx8EQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 8B01241F2D; Fri, 6 Jun 2025 16:34:56 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Jonathan Corbet Subject: [PATCH 3/9] docs: kdoc: remove the section_intro variable Date: Fri, 6 Jun 2025 10:34:32 -0600 Message-ID: <20250606163438.229916-4-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250606163438.229916-1-corbet@lwn.net> References: <20250606163438.229916-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" It is only used in one place, so just put the constant string "Introduction" there so people don't have to go looking for it. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 37b7e501af7c..90b53b70cfee 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -203,7 +203,6 @@ class KernelDoc: =20 # Section names =20 - section_intro =3D "Introduction" section_context =3D "Context" section_return =3D "Return" =20 @@ -1207,7 +1206,7 @@ class KernelDoc: self.entry.new_start_line =3D ln =20 if not doc_block.group(1): - self.entry.section =3D self.section_intro + self.entry.section =3D "Introduction" else: self.entry.section =3D doc_block.group(1) =20 --=20 2.49.0 From nobody Sat Feb 7 06:55:19 2026 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 930D7289E1D; Fri, 6 Jun 2025 16:35:03 +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=1749227705; cv=none; b=ZyKITnNCiKDaXNKVQc8YbzHTttead/e+ZWB+dz2RCpEgvODDFtmifmu1m3lRqyPDh1JDkyLFh773rx93EjeTh5qYki0ixZx9oNb+LT+zob4dYdpdtbUWbo6v62je/CTc9StenqCL6DVuoGcz5PP2D+Fwnq2tbdZYKwdEqrkknFg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749227705; c=relaxed/simple; bh=onlfVHkvysZTZ7zw4pr9BVLVORPgCRgFRMWMIg6hNn0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=VRDN+kZ0kSZX9s8RIbCL5Ekr4sDJRS7vjLpMKrGyW5aOxzKB0OCI5SiQ6bT2VRN86u9a11WfKPMO2xpiOKdT3iGrBvD1+b8gCraLEnXU7d+Ti/FSyyIdtnCCiFb38XA0eFJz8/N7uL0zdMMgmhA3AsxUahkuJXL7tfKo4OkHoyE= 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=nRvIylUf; 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="nRvIylUf" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 1CB9C41F2E DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1749227697; bh=LnZJMt1SsSLsFNAHcfhcKaeQyp6VdaCfELe/I0kOO4k=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=nRvIylUfx1svEW/nFhSR+NlvVdE/fiGZM1dPDX/GJq/qLi49jdtuanlq+N4GNQlFx GG2+0sNCMsdEc3fu+mzxlcFoRasuoHr6wf41/oAKpGfPv76DEHGdXqG3gfOwDfJ9Cw /Dd9HmBHkZ0llFs9wBr8q23V6Hoqg4HkIK+mWw+Gq5G/wwhsIPPQ6Ic3FMxcuBL6OC ugq93oO04a0ZZa18lJJSJC0RGwFYa0wg3BuXo8bdQAIhVnxsXqgEZyo+AwOx+QQs2i J1E9IxKvcSzo12dZMr5jXeAL4v48OkqUkgBsnoDYJhyNVDqBqtD8ARPndm1oTp9y4x fqhM7mG8vyOdA== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 1CB9C41F2E; Fri, 6 Jun 2025 16:34:57 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Jonathan Corbet Subject: [PATCH 4/9] docs: kdoc: simplify the kerneldoc recognition code Date: Fri, 6 Jun 2025 10:34:33 -0600 Message-ID: <20250606163438.229916-5-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250606163438.229916-1-corbet@lwn.net> References: <20250606163438.229916-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_name() looks for the first line of a kerneldoc comment. It contains two nearly identical regular expressions, the second of which only catches six cases in the kernel, all of the form: define SOME_MACRO_NAME - description Simply put the "define" into the regex and discard it, eliminating the loop and the code to remove it specially. Note that this still treats these defines as if they were functions, but that's a separate issue. There is no change in the generated output. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 24 ++++++++---------------- 1 file changed, 8 insertions(+), 16 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 90b53b70cfee..3ea260b423e2 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -1230,26 +1230,18 @@ class KernelDoc: =20 # Test for data declaration r =3D KernRe(r"^\s*\*?\s*(struct|union|enum|typedef)\b\s*(\w*)= ") + r2 =3D KernRe(fr"^{decl_start}{fn_type}(?:define\s+)?(\w+)\s*{= parenthesis}\s*{decl_end}?$") if r.search(line): self.entry.decl_type =3D r.group(1) self.entry.identifier =3D r.group(2) self.entry.is_kernel_comment =3D True - else: - # Look for foo() or static void foo() - description; - # or misspelt identifier - - r1 =3D KernRe(fr"^{decl_start}{fn_type}(\w+)\s*{parenthesi= s}\s*{decl_end}?$") - r2 =3D KernRe(fr"^{decl_start}{fn_type}(\w+[^-:]*){parenth= esis}\s*{decl_end}$") - - for r in [r1, r2]: - if r.search(line): - self.entry.identifier =3D r.group(1) - self.entry.decl_type =3D "function" - - r =3D KernRe(r"define\s+") - self.entry.identifier =3D r.sub("", self.entry.ide= ntifier) - self.entry.is_kernel_comment =3D True - break + # + # Look for a function description + # + elif r2.search(line): + self.entry.identifier =3D r2.group(1) + self.entry.decl_type =3D "function" + self.entry.is_kernel_comment =3D True =20 self.entry.identifier =3D self.entry.identifier.strip(" ") =20 --=20 2.49.0 From nobody Sat Feb 7 06:55:19 2026 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 B853E289E21; Fri, 6 Jun 2025 16:35:03 +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=1749227705; cv=none; b=UuJ04Z8nYNy7ESd9vlIs7a4OaK2c7PXacSyQgadHMjPFoGbQJ/Bb+oYtZsiupMk4+4XbybhyCXuT8PplezvywmOGHiqNferZ3Equ/PSht8F8P7tkZGTyZPyvEhjqicP8KgWg58bk82aOqimSg+66R+OW6n3dlDo2gcxK31juQw0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749227705; c=relaxed/simple; bh=4wOhT+ccdmsvlqlGTH/6VXz0OIu+as1y2XRYVinSHrc=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=WzKw186XYDJC6gNAjB7oicMDLQwep/2uIq+6/kBunGRMpqCvMPuOJLJCFYwV7ZMfB35ibiaojYH5rzqXxIIwI6EBZWzGtezAO1OBeqcEDDqh+39Cvf9hAfHvkGpdS/cUo5NofBy4J9FHckoCUEZ8BwivwIteUWT/CBFK5h2arpQ= 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=sCv2Rd85; 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="sCv2Rd85" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 9D8DD41F2F DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1749227697; bh=UYcmn4qdwBXvAETOWfKZx/qAHGOt2DuUFA6POj8NZjI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=sCv2Rd85XijSp2BAvJdjVnHYttyKZpyHIV0BUUQixj+LJVfUjLc8bN5ZKeGsYQp/b ST+9+qEdOBRKZzIF0YjTfaKv8VSWEjORxuTTEjy744TMaTV23S3WToMuH0L4LTnEOe 8GB1Ax7OroSCOfv282dyJsJH85OXjDbYIOozk6RBoIuTsvsPo7x8wCIFRDEZoIBibr MGGOwFUL7xHyh/u7bKeF1i54QwvkGb5/J9tIVuyfqQO3xJn7RFek51/Vmx2pnpZmdb qnjYDTgmXXm3qbOIUf6Q+bZpLHH4RiBTBrynr+9lIe/+GYAbiOeYvYfL+f/3e+qFk1 lfHgfMAOJnwEQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 9D8DD41F2F; Fri, 6 Jun 2025 16:34:57 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Jonathan Corbet Subject: [PATCH 5/9] docs: kdoc: remove the KernelEntry::is_kernel_comment member Date: Fri, 6 Jun 2025 10:34:34 -0600 Message-ID: <20250606163438.229916-6-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250606163438.229916-1-corbet@lwn.net> References: <20250606163438.229916-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" entry::is_kernel_comment never had anything to do with the entry itself; it is a bit of local state in one branch of process_name(). It can, in fact, be removed entirely; rework the code slightly so that it is no longer needed. No change in the rendered output. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 3ea260b423e2..56299695abd1 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -1216,7 +1216,6 @@ class KernelDoc: =20 if doc_decl.search(line): self.entry.identifier =3D doc_decl.group(1) - self.entry.is_kernel_comment =3D False =20 decl_start =3D str(doc_com) # comment block asterisk fn_type =3D r"(?:\w+\s*\*\s*)?" # type (for non-functions) @@ -1234,14 +1233,20 @@ class KernelDoc: if r.search(line): self.entry.decl_type =3D r.group(1) self.entry.identifier =3D r.group(2) - self.entry.is_kernel_comment =3D True # # Look for a function description # elif r2.search(line): self.entry.identifier =3D r2.group(1) self.entry.decl_type =3D "function" - self.entry.is_kernel_comment =3D True + # + # We struck out. + # + else: + self.emit_msg(ln, + f"This comment starts with '/**', but isn't = a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n{line}") + self.state =3D state.NORMAL + return =20 self.entry.identifier =3D self.entry.identifier.strip(" ") =20 @@ -1263,11 +1268,6 @@ class KernelDoc: else: self.entry.declaration_purpose =3D "" =20 - if not self.entry.is_kernel_comment: - self.emit_msg(ln, - f"This comment starts with '/**', but isn't = a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n{line}") - self.state =3D state.NORMAL - if not self.entry.declaration_purpose and self.config.wshort_d= esc: self.emit_msg(ln, f"missing initial short description on line:= \n{line}") --=20 2.49.0 From nobody Sat Feb 7 06:55:19 2026 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 BAB52289E26; Fri, 6 Jun 2025 16:35:03 +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=1749227705; cv=none; b=J5EGEo/hjzDkHMgcWpTM/Fyf6eHDa593I+RpiEButHLs2zMLIgHn9jVCZo7VRK7ThlcZOU4cL1djMDAfEX/PwXjqJiLroE8CCyWnXgQRJDORSBeL2MywJvKa9KyzykH894JR4k16Zk0XH6x4plz1F0x20BvRKATIQJoGhAQZPLw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749227705; c=relaxed/simple; bh=msJBqBHkePeWRZwnfqxFqzb6+do+sSPzY8HstP17mU0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=PskTbuIw3gmjOex8cshEc8Dk1TyG4JH805Ept45NZzlvBwyW3rbyhq8U6V0uEW37xePv8SUb52WBwn0T4OmImVFrKe+0XMd7Hv0pJqVTATQKngtOVadXF3+9qjLKmexcsDQDk7EvLbD7/W9wk55ASscJyNT3Pahnw6ijKlua9wg= 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=PzGPpIe9; 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="PzGPpIe9" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 2652C41F30 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1749227698; bh=Hu5hx8PEIgVdywDy22TCRt/j6m2yo0K5y93HRezRrP8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=PzGPpIe9IF9Jro50VYWitZ5NGcj+QUxDSk9XuRVTnhhV+YbWUfhsHHs7DcYXY5R+Y 51+cDdzI7Ji15S23071HoxOKD+QK7FSivT+sVcmHUvolq3wa0VPJIbq3mcStWTVWuv ISZgeu9ous3gIDK6dq6OQI8BC8czkOzqT32vg4RAWDTrT0wue3ZqKgskpohZYHb8La 7MYzassQ9uGepWjWh03PWIysnKyfdPlaEtWS/eWirii1pgLXjAtibH+xqfUOpFPQAL hqP8tb7YVZxC2cN0ctVl5AlOroGx3lOOKr2b4Abqp1WlRdSJ6B7CCrlDtF3K7+58cG 315MCIBrgC4GA== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 2652C41F30; Fri, 6 Jun 2025 16:34:58 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Jonathan Corbet Subject: [PATCH 6/9] docs: kdoc: remove the KernelEntry::descr pseudo member Date: Fri, 6 Jun 2025 10:34:35 -0600 Message-ID: <20250606163438.229916-7-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250606163438.229916-1-corbet@lwn.net> References: <20250606163438.229916-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 entry.descr value used in process_name() is not actually a member of the KernelEntry class; it is a bit of local state. So just manage it locally. A trim_whitespace() helper was added to clean up the code slightly. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 56299695abd1..7c635000f3de 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -60,6 +60,13 @@ export_symbol_ns =3D KernRe(r'^\s*EXPORT_SYMBOL_NS(_GPL)= ?\s*\(\s*(\w+)\s*,\s*"\S+" =20 type_param =3D KernRe(r"\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)", cache=3DFalse) =20 +# +# A little helper to get rid of excess white space +# +multi_space =3D KernRe(r'\s\s+') +def trim_whitespace(s): + return multi_space.sub(' ', s.strip()) + class state: """ State machine enums @@ -1258,12 +1265,7 @@ class KernelDoc: =20 r =3D KernRe("[-:](.*)") if r.search(line): - # strip leading/trailing/multiple spaces - self.entry.descr =3D r.group(1).strip(" ") - - r =3D KernRe(r"\s+") - self.entry.descr =3D r.sub(" ", self.entry.descr) - self.entry.declaration_purpose =3D self.entry.descr + self.entry.declaration_purpose =3D trim_whitespace(r.group= (1)) self.state =3D state.BODY_MAYBE else: self.entry.declaration_purpose =3D "" --=20 2.49.0 From nobody Sat Feb 7 06:55:19 2026 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 5AEBE1AF0BB; Fri, 6 Jun 2025 16:35:04 +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=1749227705; cv=none; b=CgFmMNb3eTU3hUX0MIiraB+T15i7H/8IAcr0GYrf5QYo754lp6npGa8/xRjFptOF59yFkIdTR6PPC9Voffu9skMe+0M1D9E0kGPORZPRCDe+/kvpbI4l80UndXLtuYstFpXggdxb+PgdhvdB1UNOBOgn3iwPEUfEpHuvJfqpCew= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749227705; c=relaxed/simple; bh=Um9pM2nXDiSXswpE90hcGGnYUVXZYH1viBvOkrbdVA8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=kzWuq8X7aK+0KQIREJ674frF6OQ7BZPmeqOlAerNKuESI2rOiuJ/P3efxp2f/L7kFUAkCuYaxIEDtLv6/6TC/lu7cVkqH+WCQkLuvew/KpL7Zq0EbuHMW90s17Ii0OjvM9hwdd+3ldDGSmwZsgFSI4/BllpTLAM4x++udnQO9JQ= 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=sCODYiV0; 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="sCODYiV0" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net A26FA41F31 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1749227699; bh=4khnDW8MrCmFNE79Kpf84iddwLSk1w/z1mOKhjlwzco=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=sCODYiV0TS26n2wdWWkhBUPfuYD8NibjvkKpPLYgFVhwlkRojEUylj04MYg/FkO6h eyakvAPALUt4paOcKAteTYc1TmKrupJEZwm9ofBtu4eXELgd3greKwK1JUYmCy2SoO ZjfqpSojLMqOq0HZJMq9q0+W7pjS4mJ+2qwhV/RXpcgw9/edu0Qd54UgThHMLhHmjD TpII050409HXOgZlnJdA69XJPzT6NY1Fkl4QZTqRvjz82DUQ5+rHwMZqIwqcDpgh0V ir1H8N5P4WEMfafIzrE9ULQncd/eedvaJklPmgsAZ+Zh6qjfnmibwmsskITDZU+YSV c0Y+wWjVynopg== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id A26FA41F31; Fri, 6 Jun 2025 16:34:58 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Jonathan Corbet Subject: [PATCH 7/9] docs: kdoc: remove some ineffective code Date: Fri, 6 Jun 2025 10:34:36 -0600 Message-ID: <20250606163438.229916-8-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250606163438.229916-1-corbet@lwn.net> References: <20250606163438.229916-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 code testing for a pointer declaration in process_name() has no actual effect on subsequent actions; remove it. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- 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 7c635000f3de..4e1ab28ff7cc 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -1229,11 +1229,6 @@ class KernelDoc: parenthesis =3D r"(?:\(\w*\))?" # optional parenthesis on fu= nction decl_end =3D r"(?:[-:].*)" # end of the name part =20 - # test for pointer declaration type, foo * bar() - desc - r =3D KernRe(fr"^{decl_start}([\w\s]+?){parenthesis}?\s*{decl_= end}?$") - if r.search(line): - self.entry.identifier =3D r.group(1) - # Test for data declaration r =3D KernRe(r"^\s*\*?\s*(struct|union|enum|typedef)\b\s*(\w*)= ") r2 =3D KernRe(fr"^{decl_start}{fn_type}(?:define\s+)?(\w+)\s*{= parenthesis}\s*{decl_end}?$") --=20 2.49.0 From nobody Sat Feb 7 06:55:19 2026 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 5AF6F28A1C9; Fri, 6 Jun 2025 16:35:04 +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=1749227706; cv=none; b=TQOET5g6TiyOobBslc78DOGTXWmeUiXWTnk59SX9yJxiy/NyoqWB703u2/xvnhcXlFtzMWA8OxUeRuPvRMpZHsDzuMT5dKe7PnzUbpj3QGmnhMvtT4aWEVt9Y2r6kVbvLxMmGF/fQFMKWoomR1fklyeBdtA+p0nYATMpl9k+oCI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749227706; c=relaxed/simple; bh=DIPIVjIPVmXpZgI2rlAH7UBlHZake7OmEefjqrurvNk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=ozdJ7QN34t0FvIjI2e/vbahWGA5G9J8CLHUbjFxVd7NOaEpgTWvEn0pIryuxVgoF18KHnvwzHwrvzofI+lWIlFkPD0kfb4Pbqcqqab+ZiD6sXp7kRgkAGOsjlxoOjadBu/119dHs5uKL+3Vcv1jct3GoZf1uct3PdAWKuDq4Q14= 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=S0cozf2K; 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="S0cozf2K" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 36FF441F32 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1749227699; bh=iNnVL4BxscFhHXFqnQBQA6YU9gzB5+B9LbFNv/P51Dc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=S0cozf2K5fJE7OJVUPD8V+U9jjWzv4sA6yzrvSiFnWN08bMYHhQdw8TGRdCvtSSXX ZzjtC2ZLb4BjO8Y7tlC3DqOAtas1+0/zLcPeM0DZ3x9YOG6VZsCe9sIZyHTGcz60Id 1SDO/ttjcXKLPqhV8RmD1vnbjWGziDxHh7Puy+pVLRTEoRC84W/v1I0hcNJei+MQiV QWlHIS6b79GmoEIFtN8i/bIN/RcNy8u+0lVk6w2/4MHeMIsWKWOpr4HFwmc9QwAOaq Vo646R6A02/5ATri9/fia5F1cfz+zcCRgrqhndailliyj6NDCb9uVXRAvv5nj/NtqL sHfvegRtSlOjg== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 36FF441F32; Fri, 6 Jun 2025 16:34:59 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Jonathan Corbet Subject: [PATCH 8/9] docs: kdoc: move the declaration regexes out of process_name() Date: Fri, 6 Jun 2025 10:34:37 -0600 Message-ID: <20250606163438.229916-9-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250606163438.229916-1-corbet@lwn.net> References: <20250606163438.229916-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 two complex regexes up with the other patterns, decluttering this function and allowing the compilation to be done once rather than for every kerneldoc comment. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 4e1ab28ff7cc..55f38240d4e5 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -47,7 +47,6 @@ doc_sect =3D doc_com + \ flags=3Dre.I, cache=3DFalse) =20 doc_content =3D doc_com_body + KernRe(r'(.*)', cache=3DFalse) -doc_block =3D doc_com + KernRe(r'DOC:\s*(.*)?', cache=3DFalse) doc_inline_start =3D KernRe(r'^\s*/\*\*\s*$', cache=3DFalse) doc_inline_sect =3D KernRe(r'\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)', cache=3DF= alse) doc_inline_end =3D KernRe(r'^\s*\*/\s*$', cache=3DFalse) @@ -60,6 +59,18 @@ export_symbol_ns =3D KernRe(r'^\s*EXPORT_SYMBOL_NS(_GPL)= ?\s*\(\s*(\w+)\s*,\s*"\S+" =20 type_param =3D KernRe(r"\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)", cache=3DFalse) =20 +# +# Tests for the beginning of a kerneldoc block in its various forms. +# +doc_block =3D doc_com + KernRe(r'DOC:\s*(.*)?', cache=3DFalse) +doc_begin_data =3D KernRe(r"^\s*\*?\s*(struct|union|enum|typedef)\b\s*(\w*= )", cache =3D False) +doc_begin_func =3D KernRe(str(doc_com) + # initial " * ' + r"(?:\w+\s*\*\s*)?" + # type (not captured) + r'(?:define\s+)?' + # possible "define" (not cap= tured) + r'(\w+)\s*(?:\(\w*\))?\s*' + # name and optional "= (...)" + r'(?:[-:].*)?$', # description (not captured) + cache =3D False) + # # A little helper to get rid of excess white space # @@ -1224,22 +1235,15 @@ class KernelDoc: if doc_decl.search(line): self.entry.identifier =3D doc_decl.group(1) =20 - decl_start =3D str(doc_com) # comment block asterisk - fn_type =3D r"(?:\w+\s*\*\s*)?" # type (for non-functions) - parenthesis =3D r"(?:\(\w*\))?" # optional parenthesis on fu= nction - decl_end =3D r"(?:[-:].*)" # end of the name part - # Test for data declaration - r =3D KernRe(r"^\s*\*?\s*(struct|union|enum|typedef)\b\s*(\w*)= ") - r2 =3D KernRe(fr"^{decl_start}{fn_type}(?:define\s+)?(\w+)\s*{= parenthesis}\s*{decl_end}?$") - if r.search(line): - self.entry.decl_type =3D r.group(1) - self.entry.identifier =3D r.group(2) + if doc_begin_data.search(line): + self.entry.decl_type =3D doc_begin_data.group(1) + self.entry.identifier =3D doc_begin_data.group(2) # # Look for a function description # - elif r2.search(line): - self.entry.identifier =3D r2.group(1) + elif doc_begin_func.search(line): + self.entry.identifier =3D doc_begin_func.group(1) self.entry.decl_type =3D "function" # # We struck out. --=20 2.49.0 From nobody Sat Feb 7 06:55:19 2026 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 4DD7428A1EB; Fri, 6 Jun 2025 16:35:05 +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=1749227706; cv=none; b=Nh4nr6kg/W+rLEQPNuV9i63+27LNPMMYq+pO/fgaPZEQ7PLQg0VD3Sa7eeyiaPl0pAjkynY+Kqv4R+7IWmqfBNfHQ39fgMOrsUIridlohnwIDbZX8RpAPzPIRrLLT69i9jeoiyV1QEXwgX/owuKlEQQGZTmzLjIu5bBDjfFINEc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749227706; c=relaxed/simple; bh=zOhYkWW2eaw6pPewowsMdFpcFDDAsaLaiKr3I8KJXf8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=hR4sNumsu3oyWwNjaraXKIrQaEYiwrYPxB7/HCXtoQaQdNGJuuRkUzG2kgpEmBUjAB4jvpBPPmsQuGHNy/LExC+E3nB+EzifFTnk6Cy0MlVoeRlSgsThfogcPVwE0PUBGg9E4K0xRACDMn+yBhlrs4i6xbsGLiXhKbCH+JhyJTw= 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=jQfyjNlP; 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="jQfyjNlP" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net B20FE41F33 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1749227700; bh=1nWakzCsXOuV29AJeEwLZvEN/YW1RQPl/UjXg6BHgNI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=jQfyjNlPvmy3+mdTO6xjWp6XkQR85BzjMkYIzsqx0EbFjzfId7deepSF0Ruo7qQTV PZp9CVnWDpTsGOSkANgrdsAfJZW+5Nv2ryeIiINwh0Bz3xK7iYucK4TlS1z07S2j3p bLhqHkv+llN74oKzLAmivC18SiYmjVY5dV2/+4lk/zq8Ggn4oajp/sEm6xTFS67vTG zz897Jlg7LDzXns1KEZTD7COKU3syQkmWpZs+GUh9ADCAMAo5JsLCT4VRwyCOEJlYb cN2A7HH3UJhiXEBvy68dbD7J+84rGYjm3ypAKCBk3ocs2G9kz49CRxqwyvZEp/ANI3 28weenwRXg0qQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id B20FE41F33; Fri, 6 Jun 2025 16:34:59 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Jonathan Corbet Subject: [PATCH 9/9] docs: kdoc: some final touches for process_name() Date: Fri, 6 Jun 2025 10:34:38 -0600 Message-ID: <20250606163438.229916-10-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250606163438.229916-1-corbet@lwn.net> References: <20250606163438.229916-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 process_name() to cover its broad phases of operation, and slightly restructure the if/then/else structure to remove some early returns. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 33 ++++++++++++++++++++------------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 55f38240d4e5..9a1ce6ed8605 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -1219,7 +1219,9 @@ class KernelDoc: """ STATE_NAME: Looking for the "name - description" line """ - + # + # Check for a DOC: block and handle them specially. + # if doc_block.search(line): self.entry.new_start_line =3D ln =20 @@ -1230,9 +1232,10 @@ class KernelDoc: =20 self.entry.identifier =3D self.entry.section self.state =3D state.DOCBLOCK - return - - if doc_decl.search(line): + # + # Otherwise we're looking for a normal kerneldoc declaration line. + # + elif doc_decl.search(line): self.entry.identifier =3D doc_decl.group(1) =20 # Test for data declaration @@ -1253,15 +1256,19 @@ class KernelDoc: f"This comment starts with '/**', but isn't = a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n{line}") self.state =3D state.NORMAL return - - self.entry.identifier =3D self.entry.identifier.strip(" ") - + # + # OK, set up for a new kerneldoc entry. + # self.state =3D state.BODY - + self.entry.identifier =3D self.entry.identifier.strip(" ") # if there's no @param blocks need to set up default section h= ere self.entry.section =3D SECTION_DEFAULT self.entry.new_start_line =3D ln + 1 - + # + # Find the description portion, which *should* be there but + # isn't always. + # (We should be able to capture this from the previous parsing= - someday) + # r =3D KernRe("[-:](.*)") if r.search(line): self.entry.declaration_purpose =3D trim_whitespace(r.group= (1)) @@ -1282,11 +1289,11 @@ class KernelDoc: self.emit_msg(ln, f"Scanning doc for {self.entry.decl_type} {s= elf.entry.identifier}", warning=3DFalse) - - return - + # # Failed to find an identifier. Emit a warning - self.emit_msg(ln, f"Cannot find identifier on line:\n{line}") + # + else: + self.emit_msg(ln, f"Cannot find identifier on line:\n{line}") =20 def process_body(self, ln, line): """ --=20 2.49.0