From nobody Wed Oct 8 14:18:27 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 --- 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