From nobody Wed Oct 8 12:36:08 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 13CE32EBB90; Fri, 27 Jun 2025 18:40:14 +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=1751049616; cv=none; b=PsnJJek/NYZ3pOyWPsydnq+QSNi6DlR6frN4TO1szRT1zrfqRPGIkPm5Aqqhijmi/wRo1/dfU6nIozd6TItMVqHzzcvPeI9jmvk5TfKG4F1DjQod4KrYO8I39lsO0CBZ4RlwnNO0RawDGxqgcvoTqIiJpFcQX9tQ7bvDra5bfq4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751049616; c=relaxed/simple; bh=pbTF8bWpQRIFU6pO/uLF4J0QqHJWJE0ey+E9TAEOZeE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Blejh3O2/SNe6cq0yHsurROP6kdsosfvw/9uqHgrDCP88f2HePwILSL57PcBKux8ZL+MR8HH7fbu3HPypfxs/UUvEg7hOH6suTZ1mreWO9zbVQxk+CBS6RbgUqBL2TgiZP5v/OajjuVlKjA1fegpRRQifp3iiPo25phQHUHgLD4= 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=phxri4Q2; 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="phxri4Q2" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 1AAE940AD2 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751049614; bh=+l9g5bY3dWXc9W6dNNeUJ1deRLttqcB8g4R7VVUZs2g=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=phxri4Q2D4KbcItlhTI5Q6H93CqoPf7t2m+idY6VQAt0fh/rRIm9bT/4cL9AK2roy 7/9ec5+QAv+pJVlSutvs5ASxi+qjFHo9z82RHtjju0vJj+6ydPr05jboxXoILpzX+H Sxc/vwZdbHb1FF0gX7ROkJ+WVVMc7HNIN3HhVHBFWwgFlxtf7fo5nOCr2PhBlZrCKX teF1OlM3ljjbyPPN0jkw1+LKzlEj89Y0UlNQ/o/qtPOYBPFLPNnyBTtLjgmdeQpFa+ ufftzP7Ywi9vE9dgJ3TlWo62X6ZKjjnVV6yS6XHG3xb+ahv5HNHA1XWE6T35UiwKOY I7YAHIIhi0Hdw== Received: from trenco.lwn.net (c-73-14-55-248.hsd1.co.comcast.net [73.14.55.248]) by ms.lwn.net (Postfix) with ESMTPA id 1AAE940AD2; Fri, 27 Jun 2025 18:40:14 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 1/8] docs: kdoc: remove KernelEntry::in_doc_sect Date: Fri, 27 Jun 2025 12:39:53 -0600 Message-ID: <20250627184000.132291-2-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250627184000.132291-1-corbet@lwn.net> References: <20250627184000.132291-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" This field is not used for anything, just get rid of it. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 4 ---- 1 file changed, 4 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 3557c512c85a..f3970ffbf402 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -151,8 +151,6 @@ class KernelEntry: =20 # State flags self.brcount =3D 0 - - self.in_doc_sect =3D False self.declaration_start_line =3D ln + 1 =20 # TODO: rename to emit_message after removal of kernel-doc.pl @@ -1227,7 +1225,6 @@ class KernelDoc: =20 # start a new entry self.reset_state(ln) - self.entry.in_doc_sect =3D False =20 # next line is always the function name self.state =3D state.NAME @@ -1315,7 +1312,6 @@ class KernelDoc: # def is_new_section(self, ln, line): if doc_sect.search(line): - self.entry.in_doc_sect =3D True self.state =3D state.BODY # # Pick out the name of our new section, tweaking it if need be. --=20 2.49.0 From nobody Wed Oct 8 12:36:08 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 96B712EBDF2; Fri, 27 Jun 2025 18:40:15 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751049617; cv=none; b=mRZxxHd85fY4Y8xaTGvNT5dH7WpGm5iC9QpBpWLFYJ0bCWnnPM8rHwoTtMjcHyjCcy7NXwhUnQTZyDutH/8OfeD4R4g49j9/sf2xjJNAMLOWnnZAI5r6HkCJ24iC5y/EKXxlRR+AuP2Nu1PIb+Kaxl5yMdkcsY6xG4Jfu1IHxl0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751049617; c=relaxed/simple; bh=7cMjQhucmymQ0w9SiWyAGJBSpMJ4zSOPqmEJCXm4PpE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=G12K0prv24+L6/iAqqpNuUofJJIIBP5/PE+siHrPURjJBlGMB2mR7aL9r65k7jXFX7Ysa8NNQM12VaEJXxXYb6rVqnZye4r9RO5SzUTteqM1xZVx3zt3pMxQkYrX9wZtt82sGTNeOpjB+NrzWQMtsv9qbFaDcy0TLrFn03kLvpo= 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=K9sQvt6e; 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="K9sQvt6e" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net A742440AD3 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751049615; bh=06Uw1dFoiz9YMeGTYBzxq40tnk43FQ4EMKIpINn4oWU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=K9sQvt6eGnXmNzLoW0cH03/OGtlVECVF29ifv/88WX1yX3aYMy8uRv+FIBYa+XFfY EkWPJmxsUNWL2iiy1WJb+3PXII3MEDZ/SWyKHNndN3FeRMhDlWxLBz9I8mQywmXnrs jrnkRDdjRERa2OquNMOonfVCHajLvZB1ym7aAu5NZ96KYZPE8YZOtmZMsPYKCedpS3 Ra+MXhUA4H+q8skcNWy5Z+m1TVGfg6DTbPqdhgS8epqiZfkBeKY0951esTBjwLt6n+ fCUN7a7KsUvyUW8z6MQUW8IK5vENKMsj6AsMCWy5XYX7AP4I1WZaUDKu0VvLEc7Yz1 n3r99Q7JQQlYA== Received: from trenco.lwn.net (c-73-14-55-248.hsd1.co.comcast.net [73.14.55.248]) by ms.lwn.net (Postfix) with ESMTPA id A742440AD3; Fri, 27 Jun 2025 18:40:14 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 2/8] docs: kdoc: Move content handling into KernelEntry Date: Fri, 27 Jun 2025 12:39:54 -0600 Message-ID: <20250627184000.132291-3-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250627184000.132291-1-corbet@lwn.net> References: <20250627184000.132291-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" Rather than having other code mucking around with this bit of internal state, encapsulate it internally. Accumulate the description as a list of strings, joining them at the end, which is a more efficient way of building the text. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 62 ++++++++++++++++----------------- 1 file changed, 30 insertions(+), 32 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index f3970ffbf402..f87355b63c19 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -128,7 +128,7 @@ class KernelEntry: def __init__(self, config, ln): self.config =3D config =20 - self.contents =3D "" + self._contents =3D [] self.function =3D "" self.sectcheck =3D "" self.struct_actual =3D "" @@ -153,6 +153,15 @@ class KernelEntry: self.brcount =3D 0 self.declaration_start_line =3D ln + 1 =20 + # + # Management of section contents + # + def add_text(self, text): + self._contents.append(text) + + def contents(self): + return '\n'.join(self._contents) + '\n' + # TODO: rename to emit_message after removal of kernel-doc.pl def emit_msg(self, log_msg, warning=3DTrue): """Emit a message""" @@ -180,9 +189,14 @@ class KernelEntry: """ Dumps section contents to arrays/hashes intended for that purpose. """ - + # + # If we have accumulated no contents in the default ("description") + # section, don't bother. + # + if self.section =3D=3D SECTION_DEFAULT and not self._contents: + return name =3D self.section - contents =3D self.contents + contents =3D self.contents() =20 if type_param.match(name): name =3D type_param.group(1) @@ -206,7 +220,8 @@ class KernelEntry: if name !=3D SECTION_DEFAULT: self.emit_msg(self.new_start_line, f"duplicate section name '{name}'\n") - self.sections[name] +=3D contents + # Treat as a new paragraph - add a blank line + self.sections[name] +=3D '\n' + contents else: self.sections[name] =3D contents self.sectionlist.append(name) @@ -217,7 +232,7 @@ class KernelEntry: =20 if start_new: self.section =3D SECTION_DEFAULT - self.contents =3D "" + self._contents =3D [] =20 =20 class KernelDoc: @@ -1334,16 +1349,11 @@ class KernelDoc: newcontents =3D doc_sect.group(2) if not newcontents: newcontents =3D "" - - if self.entry.contents.strip("\n"): - self.dump_section() - + self.dump_section() self.entry.begin_section(ln, newsection) self.entry.leading_space =3D None =20 - self.entry.contents =3D newcontents.lstrip() - if self.entry.contents: - self.entry.contents +=3D "\n" + self.entry.add_text(newcontents.lstrip()) return True return False =20 @@ -1385,7 +1395,6 @@ class KernelDoc: # if cont =3D=3D "": self.state =3D state.BODY - self.entry.contents +=3D "\n" # needed? # # Otherwise we have more of the declaration section to soak up. # @@ -1407,7 +1416,6 @@ class KernelDoc: # if KernRe(r"\s*\*\s*$").match(line): self.entry.begin_section(ln, dump =3D True) - self.entry.contents +=3D '\n' self.state =3D state.BODY return # @@ -1444,7 +1452,7 @@ class KernelDoc: # # Add the trimmed result to the section and we're done. # - self.entry.contents +=3D cont[self.entry.leading_space:] + '\n' + self.entry.add_text(cont[self.entry.leading_space:]) else: # Unknown line, ignore self.emit_msg(ln, f"bad line: {line}") @@ -1458,7 +1466,7 @@ class KernelDoc: =20 if doc_content.search(line): cont =3D doc_content.group(1) - self.entry.contents +=3D cont + "\n" + self.entry.add_text(cont) else: # Unknown line, ignore self.emit_msg(ln, f"bad line: {line}") @@ -1470,27 +1478,20 @@ class KernelDoc: doc_inline_sect.search(line): self.entry.begin_section(ln, doc_inline_sect.group(1)) =20 - self.entry.contents =3D doc_inline_sect.group(2).lstrip() - if self.entry.contents !=3D "": - self.entry.contents +=3D "\n" - + self.entry.add_text(doc_inline_sect.group(2).lstrip()) self.inline_doc_state =3D state.INLINE_TEXT # Documentation block end */ return =20 if doc_inline_end.search(line): - if self.entry.contents not in ["", "\n"]: - self.dump_section() - + self.dump_section() self.state =3D state.PROTO self.inline_doc_state =3D state.INLINE_NA return =20 if doc_content.search(line): if self.inline_doc_state =3D=3D state.INLINE_TEXT: - self.entry.contents +=3D doc_content.group(1) + "\n" - if not self.entry.contents.strip(" ").rstrip("\n"): - self.entry.contents =3D "" + self.entry.add_text(doc_content.group(1)) =20 elif self.inline_doc_state =3D=3D state.INLINE_NAME: self.emit_msg(ln, @@ -1668,11 +1669,8 @@ class KernelDoc: =20 if doc_inline_oneline.search(line): self.entry.begin_section(ln, doc_inline_oneline.group(1)) - self.entry.contents =3D doc_inline_oneline.group(2) - - if self.entry.contents !=3D "": - self.entry.contents +=3D "\n" - self.dump_section(start_new=3DFalse) + self.entry.add_text(doc_inline_oneline.group(2)) + self.dump_section() =20 elif doc_inline_start.search(line): self.state =3D state.INLINE @@ -1696,7 +1694,7 @@ class KernelDoc: self.reset_state(ln) =20 elif doc_content.search(line): - self.entry.contents +=3D doc_content.group(1) + "\n" + self.entry.add_text(doc_content.group(1)) =20 def parse_export(self): """ --=20 2.49.0 From nobody Wed Oct 8 12:36:08 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 3B2B12ECD02; Fri, 27 Jun 2025 18:40:15 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751049617; cv=none; b=Bz4729fkXmxsa4KUoGZzzbw6E/TzFQbNcJ/eseST6GZOKiWcm1ZITZ7ySeW37uPVNue/8AUyYZS1An173auvXbJoQLxS3ipEyRt5dmlqwsh6w+hGtmw/Hhbet2CaZqPiOQKr2OBl/sTp6DDx8wyuQaFuU0MP9FwUAPOOm9ni2hM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751049617; c=relaxed/simple; bh=PT2Yk6alDe85ukXVn62bS4QnUGmVHLMjM0JtsfhX3Xc=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=UpN1EKENeLWxLRedfqrHi16D1WO2dzm2M6TBDzl+Ze09CGVOvBw4jqfoPUCW7pswzj9xaPmpknSKoXbWHHRrx2r1T4T3GHqePYFcQ8uLh0ATYoLzaWZmR3aq6I53gqYRgmAhdf0GZhsgtAl1ozNIzc2Y7pm7pwyYbrG4/8WBMyw= 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=qwxogYrJ; 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="qwxogYrJ" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 37DCC40AD4 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751049615; bh=DSTb3QsYlsZNGDLtIkrCarnBRqRmgU+B8Ifif3GhWeA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=qwxogYrJS3aLgpJYTigefPW9n1UT+UXZUCvzf4AyL3h22Pf3To/ScvvBijCx3jI1R b3gdtEVsoCSZwNxsI9hkTiQsi+eB0JGU9Z4SfNU0bgyflu0Uo5ZBAhxXkmgpDFhEtk RK7Sc/Dhqnyhkm9f5sn3LOMn7Dc46RZwD8YADrE7zWxHPkU/0hUaxtZkr5vKvhpqBV wGhkkbILn4IzIl6P/FHTD4oxNhWLOTxX/xHB4rDbDopwBu7VTcjC6+kFZKFDH08x24 l/mE44uVorAcfit/QpeVgf2vR+Lfr6SRET66e4e18z6XBR3yRwkKtwom0NiTrFZgk4 fqzfUiv5ifGUg== Received: from trenco.lwn.net (c-73-14-55-248.hsd1.co.comcast.net [73.14.55.248]) by ms.lwn.net (Postfix) with ESMTPA id 37DCC40AD4; Fri, 27 Jun 2025 18:40:15 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 3/8] docs: kdoc: remove a bit of dead code Date: Fri, 27 Jun 2025 12:39:55 -0600 Message-ID: <20250627184000.132291-4-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250627184000.132291-1-corbet@lwn.net> References: <20250627184000.132291-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 type_param regex matches "@..." just fine, so the special-case branch for that in dump_section() is never executed. Just remove it. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 7 ------- 1 file changed, 7 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index f87355b63c19..9e46cfa20978 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -207,13 +207,6 @@ class KernelEntry: self.sectcheck +=3D name + " " self.new_start_line =3D 0 =20 - elif name =3D=3D "@...": - name =3D "..." - self.parameterdescs[name] =3D contents - self.sectcheck +=3D name + " " - self.parameterdesc_start_lines[name] =3D self.new_start_line - self.new_start_line =3D 0 - else: if name in self.sections and self.sections[name] !=3D "": # Only warn on user-specified duplicate section names --=20 2.49.0 From nobody Wed Oct 8 12:36:08 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 CEE9C2ECEA8; Fri, 27 Jun 2025 18:40:16 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751049618; cv=none; b=qNVGauktCnHtipBqlir1s2EPug92xwdQ80jb7OlAmiLXju+fNuvHZG6M9aIlaul3DN3+9AdbElBUTQDreCaoP9aaCtNso4CxVYdNaXlFJT1vbxaRapXyLv6Vv8TVO920SusvgLtIvZbHzFnMy2dZtoPojl1RN7WeTN0/6xO+DvM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751049618; c=relaxed/simple; bh=eKnkV3cRdYAzuNoW6e/CWaaa9iGwq94K82H2T+gMCX4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=u+YNxGZZ1qkFVICrjKeTekz9OZdBBX/VKg4nA06BWZyTRnUFLxcH0ayGdNc4JiZRmKrGoh2BvJe13CPLrLm+zmPLZZW/KkpTa0zV9Lcaz8JdvwnJfajdZYLsev5uAJkiYTSeHlmSquj+83eNaza86BFHwUVO1gf9JAw5Jgc4qBA= 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=W5axXksc; 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="W5axXksc" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net C372340AD5 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751049616; bh=oy2tQOVISxZN/7bzsjOD/t4NelfiJkEaBQFC9sJRccE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=W5axXkschMzOVROgnPDBZa2LW1STyyHO+0RHgTpkwvAskjAUz5aziVgyzKcTNms2R 6fg2nvgt6hu6OwhMqUiM28llMmzHrahBrMVJH3riNKTsD+MuxonxUcGPfGBHkB0uCF prQO0pOv4rQwiAR6ugRAfZle/zcmAv8zEVEzpDt9ynexj+PvG2kWp+R1qtOHQBaoRI 3ffDmQI+fK4L6NDnUmK3k4M8QV7cGroDWNL+rH7ykoIrHu7FFXMtx7Dt8UOZsUEcDv FhTTmGWTyUjymDmphUzRUJ9UJKdnmLGV0cI6SSzxgmen+nKoz5bf3FzCVNJo7zQ2Nv vsRMreOP9Lc9g== Received: from trenco.lwn.net (c-73-14-55-248.hsd1.co.comcast.net [73.14.55.248]) by ms.lwn.net (Postfix) with ESMTPA id C372340AD5; Fri, 27 Jun 2025 18:40:15 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 4/8] docs: kdoc: remove KernelEntry::function Date: Fri, 27 Jun 2025 12:39:56 -0600 Message-ID: <20250627184000.132291-5-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250627184000.132291-1-corbet@lwn.net> References: <20250627184000.132291-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" This member is unused, to take it out. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 1 - 1 file changed, 1 deletion(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 9e46cfa20978..224dea5f7c2e 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -129,7 +129,6 @@ class KernelEntry: self.config =3D config =20 self._contents =3D [] - self.function =3D "" self.sectcheck =3D "" self.struct_actual =3D "" self.prototype =3D "" --=20 2.49.0 From nobody Wed Oct 8 12:36:08 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 46F2C2ED15B; Fri, 27 Jun 2025 18:40:17 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751049618; cv=none; b=h8CZnLSx9zZaxDFZVfue6gRQ1NmIvWGs3SrL8jFjxuVGQ54tQeQOvEYw+v4FeN7ppCZsfJY9eYSxzNP26hClHQujoDZEFSP7fjr3v1nhK87/WLpRbbzZ9iAHKNIxAaHD1hOXH5gDgFMwFZ4ruIlamNxCNuhBCLIfrvaDWLywXWQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751049618; c=relaxed/simple; bh=xZ1AjPAb5peoQ2/5X0OBEamGLpA0DWBnUXtAprtIgNA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=aYZPbxXS0TMBLKtoNuIacynuvsqVgcZh2BB6reYEwy5kpPZ0nwOfziOIlWmEi3JqLDIChRYTwlLN00j0T5tKSH97AkmTPTN12MVLtttznhcMfCZ1gm4k1Lprm557qIim9eNb5YFTLi0tqdDzj1wBA0OHYpO05jG3KXEfzD68YdE= 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=rL7pGfkM; 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="rL7pGfkM" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 5CEBF40AD6 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751049616; bh=cU1j40zTmEy13wFVQwU6r+Xhna53bFvCfqjstVBxj9g=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=rL7pGfkML2l9C57A9KH/jD3e78kvdmBwezH7Dxd3cMIwkivrLOyvO9jEQQZ2lgSYG 3IBWpdZV8VOzIR7ztrp3adC9q8Kt0YjiJBNtQgSmpW7JfvIjR7kAuxh98Ofe+Vj6Ne c1ODpYxDqU3WriH01f1kaeuI3x2aq78kFbaFMcZQdDaWd6wrFd92FYNSPJnv92r+hM vE223z43DilqJEfYBHRNiO1zRMjkEMlI3VhdXcLQpibLQEH+ufQKQlaFIrugT+s1ZS zVZP5KNO7zvHWfZpkvgqDX3/DPJV1zDx8v9WECyWw7WmkqxQN0erNCUNb3sbW2s+3O W19FMSJTgdU+w== Received: from trenco.lwn.net (c-73-14-55-248.hsd1.co.comcast.net [73.14.55.248]) by ms.lwn.net (Postfix) with ESMTPA id 5CEBF40AD6; Fri, 27 Jun 2025 18:40:16 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 5/8] docs: kdoc: rework process_export() slightly Date: Fri, 27 Jun 2025 12:39:57 -0600 Message-ID: <20250627184000.132291-6-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250627184000.132291-1-corbet@lwn.net> References: <20250627184000.132291-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" Reorganize process_export() to eliminate duplicated code, don't look for exports in states where we don't expect them, and don't bother with normal state-machine processing if an export declaration has been found. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 30 ++++++++++++++---------------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 224dea5f7c2e..734b908579c3 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -1211,16 +1211,17 @@ class KernelDoc: =20 if export_symbol.search(line): symbol =3D export_symbol.group(2) - for suffix in suffixes: - symbol =3D symbol.removesuffix(suffix) - function_set.add(symbol) - return - - if export_symbol_ns.search(line): + elif export_symbol_ns.search(line): symbol =3D export_symbol_ns.group(2) - for suffix in suffixes: - symbol =3D symbol.removesuffix(suffix) - function_set.add(symbol) + else: + return False + # + # Found an export, trim out any special suffixes + # + for suffix in suffixes: + symbol =3D symbol.removesuffix(suffix) + function_set.add(symbol) + return True =20 def process_normal(self, ln, line): """ @@ -1767,13 +1768,10 @@ class KernelDoc: # it was read twice. Here, we use the already-existing # loop to parse exported symbols as well. # - # TODO: It should be noticed that not all states are - # needed here. On a future cleanup, process export only - # at the states that aren't handling comment markups. - self.process_export(export_table, line) - - # Hand this line to the appropriate state handler - self.state_actions[self.state](self, ln, line) + if (self.state !=3D state.NORMAL) or \ + not self.process_export(export_table, line): + # Hand this line to the appropriate state handler + self.state_actions[self.state](self, ln, line) =20 except OSError: self.config.log.error(f"Error: Cannot open file {self.fname}") --=20 2.49.0 From nobody Wed Oct 8 12:36:08 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 B67822ED177; Fri, 27 Jun 2025 18:40:17 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751049619; cv=none; b=RqwMMwQ+8zQrcocgDLHTXeUnP4FyrIOzwbvg+PbL+YJ/HfTfVHF1ghuL4Vz2rLNyDQj/LjNDK8g3d5g9a3h9bR4td8yZ/qaMvH/lbGzNpo5OYIKH2zT6QUMkznIBANZIohxDlL6ysdrWvmpXJF927pkuoIPNn/G2W9l/Wmw/Zro= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751049619; c=relaxed/simple; bh=lTMAGNy9jLGShROhYkdk0ytJI8mqL0/g8PTQr+cZOYA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=N1Pt3xmiPJfxcZ03Z7CDkm+Vsml0a/ZGhP0xgwIphOWBCpAmYs/subgMKqySnh6dWWN+PppHp5sOu7WuxUfU96Y16Gtoq75WJ+8gkYwwWRmGO3wfci92+BU8z9Ojk0wWfZUbw7kXj26XpwhJh05/fa2lk9FqBwk6fBFZOAoG7Zo= 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=dR79u8eP; 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="dR79u8eP" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net E2CFB40AD0 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751049617; bh=Mls0+pzTN3LHiGp7GlWLLCkLVeQdt0qpNAqNfdM34Xo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=dR79u8ePD6bYJ9iL/gNrdlmU81YmeX21pTaft+tED37sZdkuP9IUj91B64N1qfwM+ ldtEMwN00fWHm0XWRMZPOJL8CwdNl+XzQtPFRzbbanBPMgmyT4OxKb21EnO9DwYavu ZBwNLg1fGCO5q/UBScaAoS8ttOQ8fSGLaJ5OSxikr35BPZp5XSGN3XUca2b8jpAVpS mIHekLpvAVqYltoiEyS+Pj1fTkd9WGywrpD98V4HOnefRzUi0kZ5LZQDI9r3PC9PCo Gs66GntedtTZjIE/KYf/tiLF98Dxo2Fis9kPmr/Y4sNSY9d6ajJBCd8PQGoRFs2mnc msVpvTawxJetg== Received: from trenco.lwn.net (c-73-14-55-248.hsd1.co.comcast.net [73.14.55.248]) by ms.lwn.net (Postfix) with ESMTPA id E2CFB40AD0; Fri, 27 Jun 2025 18:40:16 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 6/8] docs: kdoc: remove the INLINE_END state Date: Fri, 27 Jun 2025 12:39:58 -0600 Message-ID: <20250627184000.132291-7-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250627184000.132291-1-corbet@lwn.net> References: <20250627184000.132291-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 never used, so just get rid of it. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 734b908579c3..03a0e44707a7 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -108,8 +108,7 @@ class state: INLINE_NA =3D 0 # not applicable ($state !=3D INLINE) INLINE_NAME =3D 1 # looking for member name (@foo:) INLINE_TEXT =3D 2 # looking for member documentation - INLINE_END =3D 3 # done - INLINE_ERROR =3D 4 # error - Comment without header was found. + INLINE_ERROR =3D 3 # error - Comment without header was found. # Spit a warning as it's not # proper kernel-doc and ignore the rest. =20 @@ -117,7 +116,6 @@ class state: "", "_NAME", "_TEXT", - "_END", "_ERROR", ] =20 --=20 2.49.0 From nobody Wed Oct 8 12:36:08 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 6EE622EE269; Fri, 27 Jun 2025 18:40:18 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751049620; cv=none; b=LKgBIr49Gv9fUPaJ8HaJziJwpq6uVs20gA191jHI35Me7GZCsCcZi5dbB8nWn7uuEz/lmRqJdREDOWi4zt2ACIwFEFuPJH/f3Myk87ekarjclz1v4YJeY0ffZZxTIGPneNeyfo/7hRcAZ8NQGKpgMnrRQKl8ic0od7ribSYzfbc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751049620; c=relaxed/simple; bh=gRvhyy7wVTzRIRa1gE90PymXg70C2aJ5PrOuzYoaVzI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=dNJ+WTHZE0yBpsd5A6EPsN7y8e+6R2ByBvio0qjXyi6Ip4ZvpOPnrR11RESZJWFMEZ6gTGtmBz3inPAMvQ51ByH9Q8aCoa384HhltTdO3/cdhL8/bJ7ZUKKsimYahoYq1fk2uuqDydRGSoitpiv1imUsc9U2vA7vUL5lttGD7Wg= 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=sJBPPUrj; 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="sJBPPUrj" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 7D30440AC7 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751049617; bh=J/FzKvzFoyxVTHx0W5BXoFXXd1bavPdlVAbQNxM84Po=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=sJBPPUrjVQ+MCrSUI4+HWc0JxiVaGQ2wt6giy3Q/ZaLMwKXh8KOVAZ3Dr7E4Y3q/E YwouZuQb7OwcrEXxoOJXwcc0fbKfRoXv7GMHWPjTxPcK3s7OPsNCgze45jRiGn7lMS ttFO7nrT0/Mpq8kYAje/3U0eKkyZxTBukG4EArQeGj6VbOXUTDxJ+pjlPOSVnSUhfi hBwQC8oiKsNAl7DQXKfZQ3mSReeQG1eSUfUWueNV6uBDGw+88LM//XVzf6aIdtz299 0HymE6JJIHnj6i6G0uTr/7QquQ5+mGUfKOTj1EyAQOkVNgS7h3U/9aPdJo4iYyncWd fmwsqdq2sK3xw== Received: from trenco.lwn.net (c-73-14-55-248.hsd1.co.comcast.net [73.14.55.248]) by ms.lwn.net (Postfix) with ESMTPA id 7D30440AC7; Fri, 27 Jun 2025 18:40:17 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 7/8] docs: kdoc: remove the inline states-within-a-state Date: Fri, 27 Jun 2025 12:39:59 -0600 Message-ID: <20250627184000.132291-8-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250627184000.132291-1-corbet@lwn.net> References: <20250627184000.132291-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 processing of inline kerneldoc comments is a state like the rest, but it was implemented as a set of separate substates. Just remove the substate logic and make the inline states normal ones like the rest. INLINE_ERROR was never actually used for anything, so just take it out. No changes to the generated output. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 43 ++++++++++----------------------- 1 file changed, 13 insertions(+), 30 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 03a0e44707a7..a931c1471fa8 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -91,7 +91,8 @@ class state: SPECIAL_SECTION =3D 4 # doc section ending with a blank line PROTO =3D 5 # scanning prototype DOCBLOCK =3D 6 # documentation block - INLINE =3D 7 # gathering doc outside main block + INLINE_NAME =3D 7 # gathering doc outside main block + INLINE_TEXT =3D 8 # reading the body of inline docs =20 name =3D [ "NORMAL", @@ -101,23 +102,10 @@ class state: "SPECIAL_SECTION", "PROTO", "DOCBLOCK", - "INLINE", + "INLINE_NAME", + "INLINE_TEXT", ] =20 - # Inline documentation state - INLINE_NA =3D 0 # not applicable ($state !=3D INLINE) - INLINE_NAME =3D 1 # looking for member name (@foo:) - INLINE_TEXT =3D 2 # looking for member documentation - INLINE_ERROR =3D 3 # error - Comment without header was found. - # Spit a warning as it's not - # proper kernel-doc and ignore the rest. - - inline_name =3D [ - "", - "_NAME", - "_TEXT", - "_ERROR", - ] =20 SECTION_DEFAULT =3D "Description" # default section =20 @@ -246,7 +234,6 @@ class KernelDoc: =20 # Initial state for the state machines self.state =3D state.NORMAL - self.inline_doc_state =3D state.INLINE_NA =20 # Store entry currently being processed self.entry =3D None @@ -323,7 +310,6 @@ class KernelDoc: =20 # State flags self.state =3D state.NORMAL - self.inline_doc_state =3D state.INLINE_NA =20 def push_parameter(self, ln, decl_type, param, dtype, org_arg, declaration_name): @@ -1465,30 +1451,28 @@ class KernelDoc: def process_inline(self, ln, line): """STATE_INLINE: docbook comments within a prototype.""" =20 - if self.inline_doc_state =3D=3D state.INLINE_NAME and \ + if self.state =3D=3D state.INLINE_NAME and \ doc_inline_sect.search(line): self.entry.begin_section(ln, doc_inline_sect.group(1)) =20 self.entry.add_text(doc_inline_sect.group(2).lstrip()) - self.inline_doc_state =3D state.INLINE_TEXT + self.state =3D state.INLINE_TEXT # Documentation block end */ return =20 if doc_inline_end.search(line): self.dump_section() self.state =3D state.PROTO - self.inline_doc_state =3D state.INLINE_NA return =20 if doc_content.search(line): - if self.inline_doc_state =3D=3D state.INLINE_TEXT: + if self.state =3D=3D state.INLINE_TEXT: self.entry.add_text(doc_content.group(1)) =20 - elif self.inline_doc_state =3D=3D state.INLINE_NAME: + elif self.state =3D=3D state.INLINE_NAME: self.emit_msg(ln, f"Incorrect use of kernel-doc format: {line}= ") - - self.inline_doc_state =3D state.INLINE_ERROR + self.state =3D state.PROTO =20 def syscall_munge(self, ln, proto): # pylint: disable=3DW0613 """ @@ -1664,8 +1648,7 @@ class KernelDoc: self.dump_section() =20 elif doc_inline_start.search(line): - self.state =3D state.INLINE - self.inline_doc_state =3D state.INLINE_NAME + self.state =3D state.INLINE_NAME =20 elif self.entry.decl_type =3D=3D 'function': self.process_proto_function(ln, line) @@ -1716,7 +1699,8 @@ class KernelDoc: state.BODY: process_body, state.DECLARATION: process_decl, state.SPECIAL_SECTION: process_special, - state.INLINE: process_inline, + state.INLINE_NAME: process_inline, + state.INLINE_TEXT: process_inline, state.PROTO: process_proto, state.DOCBLOCK: process_docblock, } @@ -1756,9 +1740,8 @@ class KernelDoc: prev =3D "" prev_ln =3D None =20 - self.config.log.debug("%d %s%s: %s", + self.config.log.debug("%d %s: %s", ln, state.name[self.state], - state.inline_name[self.inline_do= c_state], line) =20 # This is an optimization over the original script. --=20 2.49.0 From nobody Wed Oct 8 12:36:08 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 059EE2EE5E6; Fri, 27 Jun 2025 18:40:18 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751049620; cv=none; b=d4MNXmSeKBMXBBq0oot9aBFmOutRuD11aaCv2Box4h+klsJsoXgTiIXV9QSNsr+hyBamzvvjZVhLczFHB4KOz4BRE3hDO1LEDny1a3A4t6WQn09pMRKlLGmW6T50kZkL3EXTyarcI0ApVjmWL99KOkh7xKxa5MKCsB9CDWme6pg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751049620; c=relaxed/simple; bh=OG3Vi3/fNl/c04UvhGfqGhF0Tv6V5jD1gvt/Ro3R3vk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=XToX0qZSC9mfzgP94fGFMcpwoInjvEfvEUEn+k8U0DKdS7F4/8/PJwzibiB8w+16/VZMm2bFDXl+pfB4UyxME5UUcSbpxfFj/KzNTKwrascVUPmG4EFRcAMH24cpfOyu2FGH6gc5MkiboTliyAJEKGlibBbx0MI85Z85fMKx5/I= 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=epbttpUh; 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="epbttpUh" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 0ED7E40AD2 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751049618; bh=+iEYvlkxgBTH8QTIpp2nezk4u73s3MZGF2/w6ybXQoQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=epbttpUhMhLNmuPyKN6n7RmlJhrpM8hw/XXdJ1NFCj6s1S0zOxPEVxi/m80+ErKpf jjeD1Hx4TmacvVb4jSy86nFKe/SAgfemjPVwRKRpM8Z97fLQEsxQu4h5a/NBNQUvei pW2MidsrTMiu+f1Tke0tTdVTWTtw71BQb7Edlk06ov99GEbokEJZunDyPJ+N2rg8ZA avFgyIEqzDAqFwSCK9T2NzRCSEJLO0fw7Vy4+CSjaGkp8TGH0jkz9eg1BJcu2aX+Eg 0+1vsBHqXSOnZBs52U+ZnZISL8t6KN/h4aIQeB4MUyy/GJdwR/HzxfJ1UmsZOzYumz jq7139oGWxdzQ== Received: from trenco.lwn.net (c-73-14-55-248.hsd1.co.comcast.net [73.14.55.248]) by ms.lwn.net (Postfix) with ESMTPA id 0ED7E40AD2; Fri, 27 Jun 2025 18:40:18 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 8/8] docs: kdoc: split the processing of the two remaining inline states Date: Fri, 27 Jun 2025 12:40:00 -0600 Message-ID: <20250627184000.132291-9-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250627184000.132291-1-corbet@lwn.net> References: <20250627184000.132291-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" Now that "inline_*" are just ordinary parser states, split them into two separate functions, getting rid of some nested conditional logic. The original process_inline() would simply ignore lines that didn't match any of the regexes (those lacking the initial " * " marker). I have preserved that behavior, but we should perhaps emit a warning instead. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 37 ++++++++++++++++----------------- 1 file changed, 18 insertions(+), 19 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index a931c1471fa8..93938155fce2 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -1448,31 +1448,30 @@ class KernelDoc: # Unknown line, ignore self.emit_msg(ln, f"bad line: {line}") =20 - def process_inline(self, ln, line): - """STATE_INLINE: docbook comments within a prototype.""" + def process_inline_name(self, ln, line): + """STATE_INLINE_NAME: beginning of docbook comments within a proto= type.""" =20 - if self.state =3D=3D state.INLINE_NAME and \ - doc_inline_sect.search(line): + if doc_inline_sect.search(line): self.entry.begin_section(ln, doc_inline_sect.group(1)) - self.entry.add_text(doc_inline_sect.group(2).lstrip()) self.state =3D state.INLINE_TEXT - # Documentation block end */ - return - - if doc_inline_end.search(line): + elif doc_inline_end.search(line): self.dump_section() self.state =3D state.PROTO - return + elif doc_content.search(line): + self.emit_msg(ln, f"Incorrect use of kernel-doc format: {line}= ") + self.state =3D state.PROTO + # else ... ?? =20 - if doc_content.search(line): - if self.state =3D=3D state.INLINE_TEXT: - self.entry.add_text(doc_content.group(1)) + def process_inline_text(self, ln, line): + """STATE_INLINE_TEXT: docbook comments within a prototype.""" =20 - elif self.state =3D=3D state.INLINE_NAME: - self.emit_msg(ln, - f"Incorrect use of kernel-doc format: {line}= ") - self.state =3D state.PROTO + if doc_inline_end.search(line): + self.dump_section() + self.state =3D state.PROTO + elif doc_content.search(line): + self.entry.add_text(doc_content.group(1)) + # else ... ?? =20 def syscall_munge(self, ln, proto): # pylint: disable=3DW0613 """ @@ -1699,8 +1698,8 @@ class KernelDoc: state.BODY: process_body, state.DECLARATION: process_decl, state.SPECIAL_SECTION: process_special, - state.INLINE_NAME: process_inline, - state.INLINE_TEXT: process_inline, + state.INLINE_NAME: process_inline_name, + state.INLINE_TEXT: process_inline_text, state.PROTO: process_proto, state.DOCBLOCK: process_docblock, } --=20 2.49.0