From nobody Tue Oct 7 10:38:22 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 76AAE2951D5; Thu, 10 Jul 2025 23:31:55 +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=1752190317; cv=none; b=PfIeWQXeRXtboFKyr0yeiMqLeTAiGkxy+xDZslxIW7oCnuDyOvvMbE8uiGzT6ixlCREl9Q1IolRygZnkLya/5aRf+DFCjr6RasIx0ChsRLoGslqxENE8m3OmRzFl7GU9Bpr/k3LNpibc0i+P9Ic4k2BpUlzzf0BqvI24nyqGTek= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752190317; c=relaxed/simple; bh=qMYRnA9XGZ7/zWzvmU7F63GHBA2J7wD1/lg6b1EWtDI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Y2bG8zl1unox3drMJNLHfQ+howPGxIHpGQhiygzqXbJZJU5/ozXc7uKOSNffchlg0JSoJpIj30eyLvVaTDFNYTAp2mOHW6Y7Bw6omfQAlISR5HI+UlQz0OOiyYdjlpHdM6tJ0Tbk5m5xCSsGCmHD6ICK+cNSsb9wpNVLaiNbGkQ= 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=ppuLxiWx; 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="ppuLxiWx" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 7B1ED40ADE DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1752190314; bh=M/kKBUsmG0hdLVav5VykrUa9ChXBFaOvaMmLshR6FAk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ppuLxiWxsi3OTJSLdl+hq9aIG3oGw9gafZ3EmWzF3hDwNXiN6WfYj21+6Z06NQa84 0361ZnZCEXp8z1+cU19kcqy/dsyxvF/da8RehRHVi7coiVechnpPPxePzFnqUY4dUp mJeWxAsJ7OjA5xM6qsxLAFJVztdbSwOFgvAdRTg0qPz0aGhNkEkG398TtEJdKaZDi2 SbbrV7zn9TAxP3gPVgPPhV17ICnQR++HyQWk4Vkpbt/Ppa3Yr8SlyK3X/8Fg7ThbFL CLUi7yOHMGRrB8rW9rBcAchWazOBuCN9cxuLVFk3uV+fJ+TXoTFpb0qNIH2knrE2F5 MroCCQ7Q+p2KA== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 7B1ED40ADE; Thu, 10 Jul 2025 23:31:54 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH v2 04/12] docs: kdoc: Centralize handling of the item section list Date: Thu, 10 Jul 2025 17:31:34 -0600 Message-ID: <20250710233142.246524-5-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250710233142.246524-1-corbet@lwn.net> References: <20250710233142.246524-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 section list always comes directly from the under-construction entry and is used uniformly. Formalize section handling in the KdocItem class, and have output_declaration() load the sections directly from the entry, eliminating a lot of duplicated, verbose parameters. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_item.py | 9 +++++++++ scripts/lib/kdoc/kdoc_output.py | 36 ++++++++++++--------------------- scripts/lib/kdoc/kdoc_parser.py | 20 +++--------------- 3 files changed, 25 insertions(+), 40 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_item.py b/scripts/lib/kdoc/kdoc_item.py index add2cc772fec..f0b2b9082c56 100644 --- a/scripts/lib/kdoc/kdoc_item.py +++ b/scripts/lib/kdoc/kdoc_item.py @@ -9,6 +9,8 @@ class KdocItem: self.name =3D name self.type =3D type self.declaration_start_line =3D start_line + self.sections =3D {} + self.sections_start_lines =3D {} # # Just save everything else into our own dict so that the output # side can grab it directly as before. As we move things into more @@ -24,3 +26,10 @@ class KdocItem: =20 def __getitem__(self, key): return self.get(key) + + # + # Tracking of section information. + # + def set_sections(self, sections, start_lines): + self.sections =3D sections + self.section_start_lines =3D start_lines diff --git a/scripts/lib/kdoc/kdoc_output.py b/scripts/lib/kdoc/kdoc_output= .py index 4895c80e4b81..15cb89f91987 100644 --- a/scripts/lib/kdoc/kdoc_output.py +++ b/scripts/lib/kdoc/kdoc_output.py @@ -338,11 +338,7 @@ class RestFormat(OutputFormat): starts by putting out the name of the doc section itself, but that tends to duplicate a header already in the template file. """ - - sections =3D args.get('sections', {}) - section_start_lines =3D args.get('section_start_lines', {}) - - for section in sections: + for section, text in args.sections.items(): # Skip sections that are in the nosymbol_table if section in self.nosymbol: continue @@ -354,8 +350,8 @@ class RestFormat(OutputFormat): else: self.data +=3D f'{self.lineprefix}**{section}**\n\n' =20 - self.print_lineno(section_start_lines.get(section, 0)) - self.output_highlight(sections[section]) + self.print_lineno(args.section_start_lines.get(section, 0)) + self.output_highlight(text) self.data +=3D "\n" self.data +=3D "\n" =20 @@ -635,23 +631,20 @@ class ManFormat(OutputFormat): self.data +=3D line + "\n" =20 def out_doc(self, fname, name, args): - sections =3D args.get('sections', {}) - if not self.check_doc(name, args): return =20 self.data +=3D f'.TH "{self.modulename}" 9 "{self.modulename}" "{s= elf.man_date}" "API Manual" LINUX' + "\n" =20 - for section in sections: + for section, text in args.sections.items(): self.data +=3D f'.SH "{section}"' + "\n" - self.output_highlight(sections.get(section)) + self.output_highlight(text) =20 def out_function(self, fname, name, args): """output function in man""" =20 parameterlist =3D args.get('parameterlist', []) parameterdescs =3D args.get('parameterdescs', {}) - sections =3D args.get('sections', {}) =20 self.data +=3D f'.TH "{args["function"]}" 9 "{args["function"]}" "= {self.man_date}" "Kernel Hacker\'s Manual" LINUX' + "\n" =20 @@ -692,15 +685,14 @@ class ManFormat(OutputFormat): self.data +=3D f'.IP "{parameter}" 12' + "\n" self.output_highlight(parameterdescs.get(parameter_name, "")) =20 - for section in sections: + for section, text in args.sections.items(): self.data +=3D f'.SH "{section.upper()}"' + "\n" - self.output_highlight(sections[section]) + self.output_highlight(text) =20 def out_enum(self, fname, name, args): =20 name =3D args.get('enum', '') parameterlist =3D args.get('parameterlist', []) - sections =3D args.get('sections', {}) =20 self.data +=3D f'.TH "{self.modulename}" 9 "enum {args["enum"]}" "= {self.man_date}" "API Manual" LINUX' + "\n" =20 @@ -727,24 +719,23 @@ class ManFormat(OutputFormat): self.data +=3D f'.IP "{parameter}" 12' + "\n" self.output_highlight(args['parameterdescs'].get(parameter_nam= e, "")) =20 - for section in sections: + for section, text in args.sections.items(): self.data +=3D f'.SH "{section}"' + "\n" - self.output_highlight(sections[section]) + self.output_highlight(text) =20 def out_typedef(self, fname, name, args): module =3D self.modulename typedef =3D args.get('typedef') purpose =3D args.get('purpose') - sections =3D args.get('sections', {}) =20 self.data +=3D f'.TH "{module}" 9 "{typedef}" "{self.man_date}" "A= PI Manual" LINUX' + "\n" =20 self.data +=3D ".SH NAME\n" self.data +=3D f"typedef {typedef} \\- {purpose}\n" =20 - for section in sections: + for section, text in args.sections.items(): self.data +=3D f'.SH "{section}"' + "\n" - self.output_highlight(sections.get(section)) + self.output_highlight(text) =20 def out_struct(self, fname, name, args): module =3D self.modulename @@ -753,7 +744,6 @@ class ManFormat(OutputFormat): purpose =3D args.get('purpose') definition =3D args.get('definition') parameterlist =3D args.get('parameterlist', []) - sections =3D args.get('sections', {}) parameterdescs =3D args.get('parameterdescs', {}) =20 self.data +=3D f'.TH "{module}" 9 "{struct_type} {struct_name}" "{= self.man_date}" "API Manual" LINUX' + "\n" @@ -782,6 +772,6 @@ class ManFormat(OutputFormat): self.data +=3D f'.IP "{parameter}" 12' + "\n" self.output_highlight(parameterdescs.get(parameter_name)) =20 - for section in sections: + for section, text in args.sections.items(): self.data +=3D f'.SH "{section}"' + "\n" - self.output_highlight(sections.get(section)) + self.output_highlight(text) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 2e00c8b3a5f2..608f3a1045dc 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -272,13 +272,13 @@ class KernelDoc: item =3D KdocItem(name, dtype, self.entry.declaration_start_line, = **args) item.warnings =3D self.entry.warnings =20 - sections =3D item.get('sections', {}) - # Drop empty sections # TODO: improve empty sections logic to emit warnings + sections =3D self.entry.sections for section in ["Description", "Return"]: if section in sections and not sections[section].rstrip(): del sections[section] + item.set_sections(sections, self.entry.section_start_lines) =20 self.entries.append(item) =20 @@ -824,8 +824,6 @@ class KernelDoc: parameterdescs=3Dself.entry.parameterdescs, parametertypes=3Dself.entry.parametertypes, parameterdesc_start_lines=3Dself.entry.par= ameterdesc_start_lines, - sections=3Dself.entry.sections, - section_start_lines=3Dself.entry.section_s= tart_lines, purpose=3Dself.entry.declaration_purpose) =20 def dump_enum(self, ln, proto): @@ -908,8 +906,6 @@ class KernelDoc: parameterlist=3Dself.entry.parameterlist, parameterdescs=3Dself.entry.parameterdescs, parameterdesc_start_lines=3Dself.entry.par= ameterdesc_start_lines, - sections=3Dself.entry.sections, - section_start_lines=3Dself.entry.section_s= tart_lines, purpose=3Dself.entry.declaration_purpose) =20 def dump_declaration(self, ln, prototype): @@ -1079,8 +1075,6 @@ class KernelDoc: parameterdescs=3Dself.entry.parameterd= escs, parametertypes=3Dself.entry.parametert= ypes, parameterdesc_start_lines=3Dself.entry= .parameterdesc_start_lines, - sections=3Dself.entry.sections, - section_start_lines=3Dself.entry.secti= on_start_lines, purpose=3Dself.entry.declaration_purpo= se, func_macro=3Dfunc_macro) else: @@ -1092,8 +1086,6 @@ class KernelDoc: parameterdescs=3Dself.entry.parameterd= escs, parametertypes=3Dself.entry.parametert= ypes, parameterdesc_start_lines=3Dself.entry= .parameterdesc_start_lines, - sections=3Dself.entry.sections, - section_start_lines=3Dself.entry.secti= on_start_lines, purpose=3Dself.entry.declaration_purpo= se, func_macro=3Dfunc_macro) =20 @@ -1137,8 +1129,6 @@ class KernelDoc: parameterdescs=3Dself.entry.parameterd= escs, parametertypes=3Dself.entry.parametert= ypes, parameterdesc_start_lines=3Dself.entry= .parameterdesc_start_lines, - sections=3Dself.entry.sections, - section_start_lines=3Dself.entry.secti= on_start_lines, purpose=3Dself.entry.declaration_purpo= se) return =20 @@ -1159,8 +1149,6 @@ class KernelDoc: =20 self.output_declaration('typedef', declaration_name, typedef=3Ddeclaration_name, - sections=3Dself.entry.sections, - section_start_lines=3Dself.entry.secti= on_start_lines, purpose=3Dself.entry.declaration_purpo= se) return =20 @@ -1642,9 +1630,7 @@ class KernelDoc: =20 if doc_end.search(line): self.dump_section() - self.output_declaration("doc", self.entry.identifier, - sections=3Dself.entry.sections, - section_start_lines=3Dself.entry.secti= on_start_lines) + self.output_declaration("doc", self.entry.identifier) self.reset_state(ln) =20 elif doc_content.search(line): --=20 2.49.0