From nobody Wed Oct 8 02:02:17 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 0B94A23816C; Wed, 2 Jul 2025 22:45:59 +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=1751496361; cv=none; b=QW/PvrVi30wVwIfLcFp/OnBTJMGVvsw/5ioHsJH9st8YRBhprsneXs8xbuC4xFx2xA1RosvQe4ch5qH6HmGjvNHCV/JmmuIh3JPf3f0hN49GuJ23s5kHfHPaREa+f+nxBzsPBG0jRmufgpkDOTx+LzbPVY3nebQ+7J/evYiAvk8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751496361; c=relaxed/simple; bh=tuDS38+GKl5NVHGmUoBUyqbu3jZh3liAY+AHjAkbge4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=EDcTC5uP0kphsS7aNz7vQH+aXHgbvW0ROsy/mZ+9xw+Ee8nemmZkL6AXIbTP6/uyhgKZy0zFyDNmBttY6IyM6vuKKzhtaulwRwfyhZVySYAPPmiw8RvH7bsEkVi0K5y2ss8BLJgTHA6FJNHiuWOeLBGIvFy1UevT/OvDf+p/JB4= 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=ZdnpZRA/; 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="ZdnpZRA/" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 3009E40AAB DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751495759; bh=Iq2JARkM+RTDRXRbavedGNDVAipMfDGwc1dnxtU86WA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ZdnpZRA/bAj/Df5gdwTgA2fjeDTEGW3GnjAhHzXVo/mfH1/j9vt8zDndoSgc1Lymc zUT9bUIsRbD5Pcghb8Fnsxt4m+j/xDxn1oqkFYCIv8WJCBEijpz4MJrVkVcfpFhXtT ObdKVTA/bpnB4c1llnp/UBvghTv0jDIY0Y2dnFIj4LRvJk+tMlnzIuCoe2sow87gJ6 9wbbsqYIL6Mr8sKs9667jrnz6++s//qfljm4v+H83gTvPRpCf13cNLc1QKVUjJR6FJ qJRhNTlsd48+skhbxGwg7WSHhNwMGdXaKXqkF6jJU2yAOTWxK9OYgd9G+sGAbG/kAP gTQ2/SpkiHY9A== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 3009E40AAB; Wed, 2 Jul 2025 22:35:59 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 01/12] docs: kdoc; Add a rudimentary class to represent output items Date: Wed, 2 Jul 2025 16:35:13 -0600 Message-ID: <20250702223524.231794-2-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250702223524.231794-1-corbet@lwn.net> References: <20250702223524.231794-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 class is intended to replace the unstructured dict used to accumulate an entry to pass to an output module. For now, it remains unstructured, but it works well enough that the output classes don't notice the difference. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab Reviewed-by: Yanteng Si --- scripts/lib/kdoc/kdoc_item.py | 26 ++++++++++++++++++++++++++ scripts/lib/kdoc/kdoc_parser.py | 30 +++++++++--------------------- 2 files changed, 35 insertions(+), 21 deletions(-) create mode 100644 scripts/lib/kdoc/kdoc_item.py diff --git a/scripts/lib/kdoc/kdoc_item.py b/scripts/lib/kdoc/kdoc_item.py new file mode 100644 index 000000000000..add2cc772fec --- /dev/null +++ b/scripts/lib/kdoc/kdoc_item.py @@ -0,0 +1,26 @@ +# SPDX-License-Identifier: GPL-2.0 +# +# A class that will, eventually, encapsulate all of the parsed data that we +# then pass into the output modules. +# + +class KdocItem: + def __init__(self, name, type, start_line, **other_stuff): + self.name =3D name + self.type =3D type + self.declaration_start_line =3D start_line + # + # 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 + # structured data, this will, hopefully, fade away. + # + self.other_stuff =3D other_stuff + + def get(self, key, default =3D None): + ret =3D self.other_stuff.get(key, default) + if ret =3D=3D default: + return self.__dict__.get(key, default) + return ret + + def __getitem__(self, key): + return self.get(key) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 831f061f61b8..a5a59b97a444 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -16,7 +16,7 @@ import re from pprint import pformat =20 from kdoc_re import NestedMatch, KernRe - +from kdoc_item import KdocItem =20 # # Regular expressions used to parse kernel-doc markups at KernelDoc class. @@ -271,32 +271,20 @@ class KernelDoc: The actual output and output filters will be handled elsewhere """ =20 - # The implementation here is different than the original kernel-do= c: - # instead of checking for output filters or actually output anythi= ng, - # it just stores the declaration content at self.entries, as the - # output will happen on a separate class. - # - # For now, we're keeping the same name of the function just to make - # easier to compare the source code of both scripts - - args["declaration_start_line"] =3D self.entry.declaration_start_li= ne - args["type"] =3D dtype - args["warnings"] =3D self.entry.warnings - - # TODO: use colletions.OrderedDict to remove sectionlist + item =3D KdocItem(name, dtype, self.entry.declaration_start_line, = **args) + item.warnings =3D self.entry.warnings =20 - sections =3D args.get('sections', {}) - sectionlist =3D args.get('sectionlist', []) + sections =3D item.get('sections', {}) + sectionlist =3D item.get('sectionlist', []) =20 # Drop empty sections # TODO: improve empty sections logic to emit warnings for section in ["Description", "Return"]: - if section in sectionlist: - if not sections[section].rstrip(): - del sections[section] - sectionlist.remove(section) + if section in sectionlist and not sections[section].rstrip(): + del sections[section] + sectionlist.remove(section) =20 - self.entries.append((name, args)) + self.entries.append((name, item)) =20 self.config.log.debug("Output: %s:%s =3D %s", dtype, name, pformat= (args)) =20 --=20 2.49.0 From nobody Wed Oct 8 02:02:17 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 C975D2DE70B; Wed, 2 Jul 2025 22:45:59 +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=1751496361; cv=none; b=Pg1S1h9Nki/78zB8SMfN6z2Nrise9DZtVJWzzPBLbgtuDhUXaQLX76+0CqBoyu+plTD8PA9QLf0ms01vl+Srhz56GAtBFfviWbwucs/xiyT6dgxTglkVE88+rHP0OXp7DIjppnIHY0866Ga+8KocjhcgPYCdaxTCI3qDUSHGg70= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751496361; c=relaxed/simple; bh=JwHGt5NjOsUwLGG64Ypk9cN9UAyii+3bU4VVI7xlzwM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Nr/7nMAlfBHgUaHJOvqOjxAFXy41+6G3qdJo1AqH6QTt2k1CnrZgoNs1gvqJ2POx0rre42JGhRegM2OesXm79s0MXWDQXkwNhuSIoUoANWhsArAhNzipWlqoI1Z80qLcjS3/X5Ymef7IwWaFRVC+BxF0mpeqn9Xkjdzoh6TvN7Q= 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=n7u1RWyX; 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="n7u1RWyX" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net B2FBA40ACD DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751495760; bh=qNeEwa11KuFhFNNsoEtiOe6z2/kVZc4eBix7iuqUihE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=n7u1RWyXTaCSyOxgnAqas3LW9kpNpPMI4kC1PXxQ3/lSyRw3S9s/FPhm7VgkmNJRO OmfboYx07g28Tmt8lEmFuVzMJTyDVojnkKbBHSuFJkTS+z3spAzfm3uXK5/ToyxrA8 EvTWCZTj67+bEWaAvaHeZmz5DaXHwn9YlJUemtazjvioKTEQMGGkoE+6X2VNV/gSyc yLGp8Q4g7FFgFa2l+jyeR0UmhVfYlm9cwSLiI7vzPA1dQZ3yHGA7qrgQ0AQCtegN7G eGATw8RUIrXOj7dtTUmDdKDfcY/Ih5wxYcEOJNWfxWM0NZpHBJSKdFZQtP4XZ7NGSL 0jLKhRruL8Bug== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id B2FBA40ACD; Wed, 2 Jul 2025 22:35:59 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 02/12] docs: kdoc: simplify the output-item passing Date: Wed, 2 Jul 2025 16:35:14 -0600 Message-ID: <20250702223524.231794-3-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250702223524.231794-1-corbet@lwn.net> References: <20250702223524.231794-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 our output items contain their name, we don't need to pass it separately. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab Reviewed-by: Yanteng Si --- scripts/lib/kdoc/kdoc_files.py | 4 ++-- scripts/lib/kdoc/kdoc_parser.py | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_files.py b/scripts/lib/kdoc/kdoc_files.py index 9be4a64df71d..9e09b45b02fa 100644 --- a/scripts/lib/kdoc/kdoc_files.py +++ b/scripts/lib/kdoc/kdoc_files.py @@ -275,8 +275,8 @@ class KernelFiles(): self.config.log.warning("No kernel-doc for file %s", fname) continue =20 - for name, arg in self.results[fname]: - m =3D self.out_msg(fname, name, arg) + for arg in self.results[fname]: + m =3D self.out_msg(fname, arg.name, arg) =20 if m is None: ln =3D arg.get("ln", 0) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index a5a59b97a444..97380ff30a0d 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -284,7 +284,7 @@ class KernelDoc: del sections[section] sectionlist.remove(section) =20 - self.entries.append((name, item)) + self.entries.append(item) =20 self.config.log.debug("Output: %s:%s =3D %s", dtype, name, pformat= (args)) =20 --=20 2.49.0 From nobody Wed Oct 8 02:02:17 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 C97C41C07C3; Wed, 2 Jul 2025 22:45:59 +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=1751496361; cv=none; b=HwFgZCe1/oW8h87mbqM7qHuB6raaND0eqsBBEONkuUA0iDZ4umgE/8OFbbclDGhOyePySvue7BcuoeaXLvqNI1FVmcRy2UL1NdEq+OiuIeMDJW5ADu4nGKeFzv6gHQY+OQA6XoacEuUMtZGNbz9yHIMq2BJ2yWg+pu8BE3R5/NA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751496361; c=relaxed/simple; bh=Pgb8LSDtxIzqmAipgaHHQZ057ikA2yl3SNNhfO18ASU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=D/3GV5t7xsPrO19aStIuP8r4OTv3ivIHi0fQv5J7WTXOcbuMUQKnpdI6o2tSPEhPIv8aUaxlBfTWNdZv4YXLO+BZqWQN4muM3qPRUG/6vShXLc2kKUJmxDivMJeDaIEfwhrpDhx24BBSWHtH84FtBRAJ/JWbyByWYj2RrKcuW8E= 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=mP7rfF/L; 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="mP7rfF/L" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 4A8E840AD5 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751495760; bh=NYjm9zhDgUZ/tCYwlre9mvWRl7P3MGpd9SwqGGfx1rY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=mP7rfF/LyKKrFTLyAz4yiNh5NXnDLLO6wN1+Mt9KCLMoi3WtKyyXiFwcRghl2/Mkm zIDKQIxOKq3WhwWq92w4gcaW5ZsE0I9qId8yP5wmfRWwkOAOWn4PrX6jJ4Fa/2CMIW 2tZysPs2f3mJSjauHl1qQGM9ZN7Ja8VrN9Fg5l8RA9qKb46VdEwRngXzDmNsQ1ALEW WfrngAfyf1YKbozOFjV9xdKYM4RVCiWqCwyuAinox+db/CEnX8DdUEZ6MPZaJQzV1m JjjkmXmXLAj0v60CYZfP6Vr5CxsxN62ZClcocbu5xCvCTHG/RMJpabBROoafO47lTQ fGBi0IrWCWbPA== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 4A8E840AD5; Wed, 2 Jul 2025 22:36:00 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 03/12] docs: kdoc: drop "sectionlist" Date: Wed, 2 Jul 2025 16:35:15 -0600 Message-ID: <20250702223524.231794-4-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250702223524.231794-1-corbet@lwn.net> References: <20250702223524.231794-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" Python dicts (as of 3.7) are guaranteed to remember the insertion order of items, so we do not need a separate list for that purpose. Drop the per-entry sectionlist variable and just rely on native dict ordering. Signed-off-by: Jonathan Corbet Reviewed-by: Yanteng Si --- scripts/lib/kdoc/kdoc_output.py | 18 ++++++------------ scripts/lib/kdoc/kdoc_parser.py | 13 +------------ 2 files changed, 7 insertions(+), 24 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_output.py b/scripts/lib/kdoc/kdoc_output= .py index 86102e628d91..4895c80e4b81 100644 --- a/scripts/lib/kdoc/kdoc_output.py +++ b/scripts/lib/kdoc/kdoc_output.py @@ -339,11 +339,10 @@ class RestFormat(OutputFormat): tends to duplicate a header already in the template file. """ =20 - sectionlist =3D args.get('sectionlist', []) sections =3D args.get('sections', {}) section_start_lines =3D args.get('section_start_lines', {}) =20 - for section in sectionlist: + for section in sections: # Skip sections that are in the nosymbol_table if section in self.nosymbol: continue @@ -636,7 +635,6 @@ class ManFormat(OutputFormat): self.data +=3D line + "\n" =20 def out_doc(self, fname, name, args): - sectionlist =3D args.get('sectionlist', []) sections =3D args.get('sections', {}) =20 if not self.check_doc(name, args): @@ -644,7 +642,7 @@ class ManFormat(OutputFormat): =20 self.data +=3D f'.TH "{self.modulename}" 9 "{self.modulename}" "{s= elf.man_date}" "API Manual" LINUX' + "\n" =20 - for section in sectionlist: + for section in sections: self.data +=3D f'.SH "{section}"' + "\n" self.output_highlight(sections.get(section)) =20 @@ -653,7 +651,6 @@ class ManFormat(OutputFormat): =20 parameterlist =3D args.get('parameterlist', []) parameterdescs =3D args.get('parameterdescs', {}) - sectionlist =3D args.get('sectionlist', []) 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" @@ -695,7 +692,7 @@ class ManFormat(OutputFormat): self.data +=3D f'.IP "{parameter}" 12' + "\n" self.output_highlight(parameterdescs.get(parameter_name, "")) =20 - for section in sectionlist: + for section in sections: self.data +=3D f'.SH "{section.upper()}"' + "\n" self.output_highlight(sections[section]) =20 @@ -703,7 +700,6 @@ class ManFormat(OutputFormat): =20 name =3D args.get('enum', '') parameterlist =3D args.get('parameterlist', []) - sectionlist =3D args.get('sectionlist', []) sections =3D args.get('sections', {}) =20 self.data +=3D f'.TH "{self.modulename}" 9 "enum {args["enum"]}" "= {self.man_date}" "API Manual" LINUX' + "\n" @@ -731,7 +727,7 @@ class ManFormat(OutputFormat): self.data +=3D f'.IP "{parameter}" 12' + "\n" self.output_highlight(args['parameterdescs'].get(parameter_nam= e, "")) =20 - for section in sectionlist: + for section in sections: self.data +=3D f'.SH "{section}"' + "\n" self.output_highlight(sections[section]) =20 @@ -739,7 +735,6 @@ class ManFormat(OutputFormat): module =3D self.modulename typedef =3D args.get('typedef') purpose =3D args.get('purpose') - sectionlist =3D args.get('sectionlist', []) sections =3D args.get('sections', {}) =20 self.data +=3D f'.TH "{module}" 9 "{typedef}" "{self.man_date}" "A= PI Manual" LINUX' + "\n" @@ -747,7 +742,7 @@ class ManFormat(OutputFormat): self.data +=3D ".SH NAME\n" self.data +=3D f"typedef {typedef} \\- {purpose}\n" =20 - for section in sectionlist: + for section in sections: self.data +=3D f'.SH "{section}"' + "\n" self.output_highlight(sections.get(section)) =20 @@ -757,7 +752,6 @@ class ManFormat(OutputFormat): struct_name =3D args.get('struct') purpose =3D args.get('purpose') definition =3D args.get('definition') - sectionlist =3D args.get('sectionlist', []) parameterlist =3D args.get('parameterlist', []) sections =3D args.get('sections', {}) parameterdescs =3D args.get('parameterdescs', {}) @@ -788,6 +782,6 @@ class ManFormat(OutputFormat): self.data +=3D f'.IP "{parameter}" 12' + "\n" self.output_highlight(parameterdescs.get(parameter_name)) =20 - for section in sectionlist: + for section in sections: self.data +=3D f'.SH "{section}"' + "\n" self.output_highlight(sections.get(section)) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 97380ff30a0d..2e00c8b3a5f2 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -127,7 +127,6 @@ class KernelEntry: self.parameterdesc_start_lines =3D {} =20 self.section_start_lines =3D {} - self.sectionlist =3D [] self.sections =3D {} =20 self.anon_struct_union =3D False @@ -202,7 +201,6 @@ class KernelEntry: self.sections[name] +=3D '\n' + contents else: self.sections[name] =3D contents - self.sectionlist.append(name) self.section_start_lines[name] =3D self.new_start_line self.new_start_line =3D 0 =20 @@ -275,14 +273,12 @@ class KernelDoc: item.warnings =3D self.entry.warnings =20 sections =3D item.get('sections', {}) - sectionlist =3D item.get('sectionlist', []) =20 # Drop empty sections # TODO: improve empty sections logic to emit warnings for section in ["Description", "Return"]: - if section in sectionlist and not sections[section].rstrip(): + if section in sections and not sections[section].rstrip(): del sections[section] - sectionlist.remove(section) =20 self.entries.append(item) =20 @@ -828,7 +824,6 @@ class KernelDoc: parameterdescs=3Dself.entry.parameterdescs, parametertypes=3Dself.entry.parametertypes, parameterdesc_start_lines=3Dself.entry.par= ameterdesc_start_lines, - sectionlist=3Dself.entry.sectionlist, sections=3Dself.entry.sections, section_start_lines=3Dself.entry.section_s= tart_lines, purpose=3Dself.entry.declaration_purpose) @@ -913,7 +908,6 @@ class KernelDoc: parameterlist=3Dself.entry.parameterlist, parameterdescs=3Dself.entry.parameterdescs, parameterdesc_start_lines=3Dself.entry.par= ameterdesc_start_lines, - sectionlist=3Dself.entry.sectionlist, sections=3Dself.entry.sections, section_start_lines=3Dself.entry.section_s= tart_lines, purpose=3Dself.entry.declaration_purpose) @@ -1085,7 +1079,6 @@ class KernelDoc: parameterdescs=3Dself.entry.parameterd= escs, parametertypes=3Dself.entry.parametert= ypes, parameterdesc_start_lines=3Dself.entry= .parameterdesc_start_lines, - sectionlist=3Dself.entry.sectionlist, sections=3Dself.entry.sections, section_start_lines=3Dself.entry.secti= on_start_lines, purpose=3Dself.entry.declaration_purpo= se, @@ -1099,7 +1092,6 @@ class KernelDoc: parameterdescs=3Dself.entry.parameterd= escs, parametertypes=3Dself.entry.parametert= ypes, parameterdesc_start_lines=3Dself.entry= .parameterdesc_start_lines, - sectionlist=3Dself.entry.sectionlist, sections=3Dself.entry.sections, section_start_lines=3Dself.entry.secti= on_start_lines, purpose=3Dself.entry.declaration_purpo= se, @@ -1145,7 +1137,6 @@ class KernelDoc: parameterdescs=3Dself.entry.parameterd= escs, parametertypes=3Dself.entry.parametert= ypes, parameterdesc_start_lines=3Dself.entry= .parameterdesc_start_lines, - sectionlist=3Dself.entry.sectionlist, sections=3Dself.entry.sections, section_start_lines=3Dself.entry.secti= on_start_lines, purpose=3Dself.entry.declaration_purpo= se) @@ -1168,7 +1159,6 @@ class KernelDoc: =20 self.output_declaration('typedef', declaration_name, typedef=3Ddeclaration_name, - sectionlist=3Dself.entry.sectionlist, sections=3Dself.entry.sections, section_start_lines=3Dself.entry.secti= on_start_lines, purpose=3Dself.entry.declaration_purpo= se) @@ -1653,7 +1643,6 @@ class KernelDoc: if doc_end.search(line): self.dump_section() self.output_declaration("doc", self.entry.identifier, - sectionlist=3Dself.entry.sectionlist, sections=3Dself.entry.sections, section_start_lines=3Dself.entry.secti= on_start_lines) self.reset_state(ln) --=20 2.49.0 From nobody Wed Oct 8 02:02:17 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 0B8BF21770B; Wed, 2 Jul 2025 22:45:59 +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=1751496361; cv=none; b=KP4gN7s87XhQ5bgrKsjqdJqkjAXYLeZ+9Q7J+amRHumIa6728e+QRjwoDGURDFfXzZDhTF7YQExlRd7BIV1FspMsAmgjGS83HBebtro46/MqnEbj3amtOhtQnsRVIqgHhKCTHuDOD4mZd7/5MTK1BRHS+X8bz9YXNSoMQt7AyG8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751496361; c=relaxed/simple; bh=UPS3jRecEgBaQrFDvJUIey28qto38FfAohZ6dAgaey8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=iDBV2CFVIOqXvNC0rbWysm/Posjaiex6liktgvshC4pforpbY+/8X1Ey3FVYdIg0uaeSKcPFPhl+ogRIOaFpEhkFOgbCIRIvnAHLubb1s2XA8z9/ATzd6/wjF0xNkqwtzBkQyMKpY/v1v9O8yM9/ey69ZePfct3WfbCVbboPxzI= 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=KvS4CyeV; 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="KvS4CyeV" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net D13E440AD6 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751495761; bh=/IXkiFnHxKywSEBZcmAZNPVT8JLzPS8dyYGnsbT50ws=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=KvS4CyeVaC8a0sxpwR43rOHRMW3jcor+9DSHtk5uzdQDG6xTjocJpgloDaT9W6vJF knUAKp9elkA6NreE+rup+gXKwpJieNqPotvRY1JrP4KZQzN2X/yYHXXm5MPzJ8h9aY vZnaiOxyJ+2Gofiofppjk9jG2As7tg0kbju3nuJ1a6qm9nnempNvi6F7tlBa1UgzMi esnPLlJ+/2ZTOW5qRu7Zy+DEXOPw+VRCgYNwlM0XJoOFstDoox9lxNfkZYKG0lh9de TMDsNawsVv6YK10Ohf4lfu63jAuzIU0K+6YyWiG8vBcMCzU/DznQ3GZ5tAQeb6FxYz oHWhc8ottBSvA== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id D13E440AD6; Wed, 2 Jul 2025 22:36:00 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 04/12] docs: kdoc: Centralize handling of the item section list Date: Wed, 2 Jul 2025 16:35:16 -0600 Message-ID: <20250702223524.231794-5-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250702223524.231794-1-corbet@lwn.net> References: <20250702223524.231794-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: Yanteng Si --- scripts/lib/kdoc/kdoc_item.py | 8 ++++++++ scripts/lib/kdoc/kdoc_output.py | 36 ++++++++++++--------------------- scripts/lib/kdoc/kdoc_parser.py | 20 +++--------------- 3 files changed, 24 insertions(+), 40 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_item.py b/scripts/lib/kdoc/kdoc_item.py index add2cc772fec..c8329019a219 100644 --- a/scripts/lib/kdoc/kdoc_item.py +++ b/scripts/lib/kdoc/kdoc_item.py @@ -9,6 +9,7 @@ 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 +25,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 From nobody Wed Oct 8 02:02:17 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 A8421BA2E; Wed, 2 Jul 2025 22:36: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=1751495767; cv=none; b=BO2awDS2yqOJluLQ8djjqGx+Tq4tpq4ruIlE4KoZrQ5xmP5Q+ofF849cOsLHUlv/aqUo/Ag4v6Z71H9OEopTOYSW+PGJwJushLPbw4VOnJdihUhNwcjGuoE+zvA9uLtBHI9Vu+ldvh/p9CAMJ2JhgYteVrt1ishJCRVAhh/kIW4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751495767; c=relaxed/simple; bh=oZuV8TXB0zmFmNtykCVMbeVWfcnuP0A42EsvLKTwol8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=UfGzdiOQ1RXB7BfUdCdfa5SkEcMSdkWjsEHuvLb+LcLP7lQw2ZxKFDE3meQdZykg5XlbQsCUtsOnnmne5bEegdxijaJfcsSfgdmkHQVD+INhpxWlM1tutro4ZFpKdjS5U2ZVs15b+zEb6PW+2Y4Vd1fPzkmiEEYFkdcN0JYyYCA= 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=ZKCmdI9a; 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="ZKCmdI9a" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 69B8E40AD7 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751495761; bh=atGQI8ciMQaBSgY8/Pnz9IPDBgayT8RIht1YuEDa/kE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ZKCmdI9a6ouhaRpb0abiFSNJ9NxywoLe4apaimyq4aR8hb7vV43HkMkyvFXlYsslw 1+w/zDtnCkTT23Hv+t+UFPwwRBD0jk0XYStbPY2jkzVD9yUb9fFwx9sATBNSuV/J1i PvbU5OIxM5pndAqeSDBaRIu0TamqyYncsZhuvALzIYdA6k8QKBtWDGuS5GYpAG5YOG knun8egBwzPDlPrOMPg418ZrsvJMDUgjI99DPkbb1L3oPEBbmTx9HSBlA8efEK3QkX qKVV5QEeZG+vKaAExLO8dMdQFde88nDq66fHQsc2LrE27rhgGt6oVLbmZTGg1FeAli GlHO4akNXYHYQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 69B8E40AD7; Wed, 2 Jul 2025 22:36:01 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 05/12] docs: kdoc: remove the "struct_actual" machinery Date: Wed, 2 Jul 2025 16:35:17 -0600 Message-ID: <20250702223524.231794-6-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250702223524.231794-1-corbet@lwn.net> References: <20250702223524.231794-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 goes out of its way to create a special list of parameters in entry.struct_actual that is just like entry.parameterlist, but with extra junk. The only use of that information, in check_sections(), promptly strips all the extra junk back out. Drop all that extra work and just use parameterlist. No output changes. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab Reviewed-by: Yanteng Si --- scripts/lib/kdoc/kdoc_parser.py | 32 ++------------------------------ 1 file changed, 2 insertions(+), 30 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 608f3a1045dc..b28f056365cb 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -116,7 +116,6 @@ class KernelEntry: =20 self._contents =3D [] self.sectcheck =3D "" - self.struct_actual =3D "" self.prototype =3D "" =20 self.warnings =3D [] @@ -366,15 +365,6 @@ class KernelDoc: org_arg =3D KernRe(r'\s\s+').sub(' ', org_arg) self.entry.parametertypes[param] =3D org_arg =20 - def save_struct_actual(self, actual): - """ - Strip all spaces from the actual param so that it looks like - one string item. - """ - - actual =3D KernRe(r'\s*').sub("", actual, count=3D1) - - self.entry.struct_actual +=3D actual + " " =20 def create_parameter_list(self, ln, decl_type, args, splitter, declaration_name): @@ -420,7 +410,6 @@ class KernelDoc: param =3D arg =20 dtype =3D KernRe(r'([^\(]+\(\*?)\s*' + re.escape(param)).s= ub(r'\1', arg) - self.save_struct_actual(param) self.push_parameter(ln, decl_type, param, dtype, arg, declaration_name) =20 @@ -437,7 +426,6 @@ class KernelDoc: =20 dtype =3D KernRe(r'([^\(]+\(\*?)\s*' + re.escape(param)).s= ub(r'\1', arg) =20 - self.save_struct_actual(param) self.push_parameter(ln, decl_type, param, dtype, arg, declaration_name) =20 @@ -470,7 +458,6 @@ class KernelDoc: =20 param =3D r.group(1) =20 - self.save_struct_actual(r.group(2)) self.push_parameter(ln, decl_type, r.group(2), f"{dtype} {r.group(1)}", arg, declaration_name) @@ -482,12 +469,10 @@ class KernelDoc: continue =20 if dtype !=3D "": # Skip unnamed bit-fields - self.save_struct_actual(r.group(1)) self.push_parameter(ln, decl_type, r.group(1), f"{dtype}:{r.group(2)}", arg, declaration_name) else: - self.save_struct_actual(param) self.push_parameter(ln, decl_type, param, dtype, arg, declaration_name) =20 @@ -499,24 +484,11 @@ class KernelDoc: =20 sects =3D sectcheck.split() prms =3D prmscheck.split() - err =3D False =20 for sx in range(len(sects)): # pylint: disable=3D= C0200 err =3D True for px in range(len(prms)): # pylint: disable=3D= C0200 - prm_clean =3D prms[px] - prm_clean =3D KernRe(r'\[.*\]').sub('', prm_clean) - prm_clean =3D attribute.sub('', prm_clean) - - # ignore array size in a parameter string; - # however, the original param string may contain - # spaces, e.g.: addr[6 + 2] - # and this appears in @prms as "addr[6" since the - # parameter list is split at spaces; - # hence just ignore "[..." for the sections check; - prm_clean =3D KernRe(r'\[.*').sub('', prm_clean) - - if prm_clean =3D=3D sects[sx]: + if prms[px] =3D=3D sects[sx]: err =3D False break =20 @@ -782,7 +754,7 @@ class KernelDoc: self.create_parameter_list(ln, decl_type, members, ';', declaration_name) self.check_sections(ln, declaration_name, decl_type, - self.entry.sectcheck, self.entry.struct_actual) + self.entry.sectcheck, ' '.join(self.entry.para= meterlist)) =20 # Adjust declaration for better display declaration =3D KernRe(r'([\{;])').sub(r'\1\n', declaration) --=20 2.49.0 From nobody Wed Oct 8 02:02:17 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 A84647E0E4; Wed, 2 Jul 2025 22:36: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=1751495767; cv=none; b=ns87/ly8XaRBpOmTjJ4GNmMPOGtk4IXHTbjOvC2QV27FIccNuLUBYQsjzNEl1aNKZwE2lsJZbSbMY5sDGpmY2suo8LgB9Ii/1apjCEnYRy0L9dqVF//PLFnwW6pBdwe14CgNAfZ4PYfhVFc7QKJNUp/zKUqojdm6UhAYgKYUaK0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751495767; c=relaxed/simple; bh=FwhImwbafGh/zSIx/tFbbpugx28qhWcgTkn8+5R/NgI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=itOXmXqSPeyyYnnQyKgCr80yxeGQ+ZAvjWqUXgo4A2e62fhAk1TK/joJYz+osPfMRDa/zHn8BnDbWdFZkgJvPmfEvqXM8B3awkVXZglTxRIyEnszt3WkShlkm6kx89dpUCIsdR6rfHmZ/AJv+la8reN3tlenCFIgUXH0n/+YMO8= 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=JgeSRHRT; 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="JgeSRHRT" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net EF6F040AD8 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751495762; bh=DTvXcrbBitRgXHw7xikNWkgt0Dd2ojvGet8pYn6xCbI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=JgeSRHRTh7KmdIczkY+8jBtbz2xFOEH7ldbEQ0Y3jVA3k5r28AnX5OL9rGH4Hu4MP QKeQPhjetk2ylXHZGc63iCApJp57z5MAD0b3CR34jrdl3C94PAKJIIL721opT9Wj5/ 8V73PGGD8RnNllEAlWJI3tzk97+9i8YG8ZxiAvRkd6f89nl2wCzBNV95VkIuJGY0LO 3uZxQyZ4t8oFayLvtdxG4B5a5I08MPjmQamrfXSXzRZtBs9/rlH676/Abjovz8d6Hv 4Y2aYeCleYvhZj9Cc4aAf/w3Z35Ol9Zqh2TxMbSqRSVInkNFS5yTrPbJmdY6VqPIO0 szkrUKslj9nmA== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id EF6F040AD8; Wed, 2 Jul 2025 22:36:01 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 06/12] docs: kdoc: use self.entry.parameterlist directly in check_sections() Date: Wed, 2 Jul 2025 16:35:18 -0600 Message-ID: <20250702223524.231794-7-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250702223524.231794-1-corbet@lwn.net> References: <20250702223524.231794-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" Callers of check_sections() join parameterlist into a single string, which is then immediately split back into the original list. Rather than do all that, just use parameterlist directly in check_sections(). Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab Reviewed-by: Yanteng Si --- scripts/lib/kdoc/kdoc_parser.py | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index b28f056365cb..ffd49f9395ae 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -476,19 +476,18 @@ class KernelDoc: self.push_parameter(ln, decl_type, param, dtype, arg, declaration_name) =20 - def check_sections(self, ln, decl_name, decl_type, sectcheck, prmschec= k): + def check_sections(self, ln, decl_name, decl_type, sectcheck): """ Check for errors inside sections, emitting warnings if not found parameters are described. """ =20 sects =3D sectcheck.split() - prms =3D prmscheck.split() =20 for sx in range(len(sects)): # pylint: disable=3D= C0200 err =3D True - for px in range(len(prms)): # pylint: disable=3D= C0200 - if prms[px] =3D=3D sects[sx]: + for param in self.entry.parameterlist: + if param =3D=3D sects[sx]: err =3D False break =20 @@ -753,8 +752,7 @@ class KernelDoc: =20 self.create_parameter_list(ln, decl_type, members, ';', declaration_name) - self.check_sections(ln, declaration_name, decl_type, - self.entry.sectcheck, ' '.join(self.entry.para= meterlist)) + self.check_sections(ln, declaration_name, decl_type, self.entry.se= ctcheck) =20 # Adjust declaration for better display declaration =3D KernRe(r'([\{;])').sub(r'\1\n', declaration) @@ -1032,9 +1030,7 @@ class KernelDoc: f"expecting prototype for {self.entry.identifier= }(). Prototype was for {declaration_name}() instead") return =20 - prms =3D " ".join(self.entry.parameterlist) - self.check_sections(ln, declaration_name, "function", - self.entry.sectcheck, prms) + self.check_sections(ln, declaration_name, "function", self.entry.s= ectcheck) =20 self.check_return_section(ln, declaration_name, return_type) =20 --=20 2.49.0 From nobody Wed Oct 8 02:02:17 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 A84C91D2F42; Wed, 2 Jul 2025 22:36: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=1751495767; cv=none; b=GHuzsTwNoOliegV37HJOpMWUUWcQC/wHsi0WU30ajXvezLwbdOejGgkbPewAU4brBSkrqrjZDS7cfDljq1vSp/+H3I0j07kuAkyEf0xXJY2Y4XWVVhEcH81WusbkaNyhkWvssIbR7qMcQ8JNvzLF251weK8hhFm4cLF3j5D3OdE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751495767; c=relaxed/simple; bh=VjQl6YiCIhW31B/PL/n1rI7O0Jsi8wgOTJThGm1l5Ew=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=ab47neANPjrMEMPxU4ZcQjTvXI1PvuMs1Z57rWqxjmutF+rZ2s6xKxMMgOgagP+5h9/kqMKsapss8OvdXpKkBv26NPTGp3afDZT6p3bH0ti2sSBS9vVVpnMCgzzxApZPi+j4vC52NUpq+V1LYqjLzz9nvV2Cw4C+iEWPtx4qWOs= 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=i/aJ7COE; 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="i/aJ7COE" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 7FF8740AD9 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751495762; bh=trjDihqMUa1Z5UUdsfSeZ8jUyx+6GMcnDJxT4xD202g=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=i/aJ7COEXuPlx8HUW/050/ssf8Bpvo7sp2uHzYlTtEaDpt6zrBlVfIgEP+E37sSRJ 7wCTEdZWq+YZIs7nMr29vOIEe6LY2m+BsaACtc0KRmUMcAeUtCgyRp4H3zpwRPI0nG n/ZmDKBvjN0ElaP19pieKdqendLprFPfTAvS2nm/kSRMt/4aejq97fNxgAeJNKpGRC MbwQPKRqsUbU3D9IthqTQ80jNPW04BaKQHykhqeAI3XO8D8YXJsMEOIu0u7uTn4cw3 dSPmF5m+2CmX39p0EOe/fxj3rXWCAiWrmc9vJwwjGADuDwUyLC4yfFU6pKt1oGGlva 3XwfXa6ceeFYQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 7FF8740AD9; Wed, 2 Jul 2025 22:36:02 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 07/12] docs: kdoc: Coalesce parameter-list handling Date: Wed, 2 Jul 2025 16:35:19 -0600 Message-ID: <20250702223524.231794-8-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250702223524.231794-1-corbet@lwn.net> References: <20250702223524.231794-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" Callers to output_declaration() always pass the parameter information from self.entry; remove all of the boilerplate arguments and just get at that information directly. Formalize its placement in the KdocItem class. It would be nice to get rid of parameterlist as well, but that has the effect of reordering the output of function parameters and struct fields to match the order in the kerneldoc comment rather than in the declaration. One could argue about which is more correct, but the ordering has been left unchanged for now. Signed-off-by: Jonathan Corbet Reviewed-by: Yanteng Si --- scripts/lib/kdoc/kdoc_item.py | 10 ++++- scripts/lib/kdoc/kdoc_output.py | 75 +++++++++++++-------------------- scripts/lib/kdoc/kdoc_parser.py | 23 ++-------- 3 files changed, 41 insertions(+), 67 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_item.py b/scripts/lib/kdoc/kdoc_item.py index c8329019a219..51e8669b9a6e 100644 --- a/scripts/lib/kdoc/kdoc_item.py +++ b/scripts/lib/kdoc/kdoc_item.py @@ -10,6 +10,8 @@ class KdocItem: self.type =3D type self.declaration_start_line =3D start_line self.sections =3D self.sections_start_lines =3D { } + self.parameterlist =3D self.parameterdesc_start_lines =3D [] + self.parameterdescs =3D self.parametertypes =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 @@ -27,8 +29,14 @@ class KdocItem: return self.get(key) =20 # - # Tracking of section information. + # Tracking of section and parameter information. # def set_sections(self, sections, start_lines): self.sections =3D sections self.section_start_lines =3D start_lines + + def set_params(self, names, descs, types, starts): + self.parameterlist =3D names + self.parameterdescs =3D descs + self.parametertypes =3D types + self.parameterdesc_start_lines =3D starts diff --git a/scripts/lib/kdoc/kdoc_output.py b/scripts/lib/kdoc/kdoc_output= .py index 15cb89f91987..d6f4d9e7173b 100644 --- a/scripts/lib/kdoc/kdoc_output.py +++ b/scripts/lib/kdoc/kdoc_output.py @@ -373,18 +373,13 @@ class RestFormat(OutputFormat): signature =3D args['functiontype'] + " " signature +=3D args['function'] + " (" =20 - parameterlist =3D args.get('parameterlist', []) - parameterdescs =3D args.get('parameterdescs', {}) - parameterdesc_start_lines =3D args.get('parameterdesc_start_lines'= , {}) - ln =3D args.get('declaration_start_line', 0) - count =3D 0 - for parameter in parameterlist: + for parameter in args.parameterlist: if count !=3D 0: signature +=3D ", " count +=3D 1 - dtype =3D args['parametertypes'].get(parameter, "") + dtype =3D args.parametertypes.get(parameter, "") =20 if function_pointer.search(dtype): signature +=3D function_pointer.group(1) + parameter + fun= ction_pointer.group(3) @@ -419,26 +414,26 @@ class RestFormat(OutputFormat): # function prototypes apart self.lineprefix =3D " " =20 - if parameterlist: + if args.parameterlist: self.data +=3D ".. container:: kernelindent\n\n" self.data +=3D f"{self.lineprefix}**Parameters**\n\n" =20 - for parameter in parameterlist: + for parameter in args.parameterlist: parameter_name =3D KernRe(r'\[.*').sub('', parameter) - dtype =3D args['parametertypes'].get(parameter, "") + dtype =3D args.parametertypes.get(parameter, "") =20 if dtype: self.data +=3D f"{self.lineprefix}``{dtype}``\n" else: self.data +=3D f"{self.lineprefix}``{parameter}``\n" =20 - self.print_lineno(parameterdesc_start_lines.get(parameter_name= , 0)) + self.print_lineno(args.parameterdesc_start_lines.get(parameter= _name, 0)) =20 self.lineprefix =3D " " - if parameter_name in parameterdescs and \ - parameterdescs[parameter_name] !=3D KernelDoc.undescribed: + if parameter_name in args.parameterdescs and \ + args.parameterdescs[parameter_name] !=3D KernelDoc.undescri= bed: =20 - self.output_highlight(parameterdescs[parameter_name]) + self.output_highlight(args.parameterdescs[parameter_name]) self.data +=3D "\n" else: self.data +=3D f"{self.lineprefix}*undescribed*\n\n" @@ -451,8 +446,6 @@ class RestFormat(OutputFormat): =20 oldprefix =3D self.lineprefix name =3D args.get('enum', '') - parameterlist =3D args.get('parameterlist', []) - parameterdescs =3D args.get('parameterdescs', {}) ln =3D args.get('declaration_start_line', 0) =20 self.data +=3D f"\n\n.. c:enum:: {name}\n\n" @@ -467,11 +460,11 @@ class RestFormat(OutputFormat): self.lineprefix =3D outer + " " self.data +=3D f"{outer}**Constants**\n\n" =20 - for parameter in parameterlist: + for parameter in args.parameterlist: self.data +=3D f"{outer}``{parameter}``\n" =20 - if parameterdescs.get(parameter, '') !=3D KernelDoc.undescribe= d: - self.output_highlight(parameterdescs[parameter]) + if args.parameterdescs.get(parameter, '') !=3D KernelDoc.undes= cribed: + self.output_highlight(args.parameterdescs[parameter]) else: self.data +=3D f"{self.lineprefix}*undescribed*\n\n" self.data +=3D "\n" @@ -505,10 +498,6 @@ class RestFormat(OutputFormat): dtype =3D args.get('type', "struct") ln =3D args.get('declaration_start_line', 0) =20 - parameterlist =3D args.get('parameterlist', []) - parameterdescs =3D args.get('parameterdescs', {}) - parameterdesc_start_lines =3D args.get('parameterdesc_start_lines'= , {}) - self.data +=3D f"\n\n.. c:{dtype}:: {name}\n\n" =20 self.print_lineno(ln) @@ -531,21 +520,21 @@ class RestFormat(OutputFormat): =20 self.lineprefix =3D " " self.data +=3D f"{self.lineprefix}**Members**\n\n" - for parameter in parameterlist: + for parameter in args.parameterlist: if not parameter or parameter.startswith("#"): continue =20 parameter_name =3D parameter.split("[", maxsplit=3D1)[0] =20 - if parameterdescs.get(parameter_name) =3D=3D KernelDoc.undescr= ibed: + if args.parameterdescs.get(parameter_name) =3D=3D KernelDoc.un= described: continue =20 - self.print_lineno(parameterdesc_start_lines.get(parameter_name= , 0)) + self.print_lineno(args.parameterdesc_start_lines.get(parameter= _name, 0)) =20 self.data +=3D f"{self.lineprefix}``{parameter}``\n" =20 self.lineprefix =3D " " - self.output_highlight(parameterdescs[parameter_name]) + self.output_highlight(args.parameterdescs[parameter_name]) self.lineprefix =3D " " =20 self.data +=3D "\n" @@ -643,9 +632,6 @@ class ManFormat(OutputFormat): def out_function(self, fname, name, args): """output function in man""" =20 - parameterlist =3D args.get('parameterlist', []) - parameterdescs =3D args.get('parameterdescs', {}) - self.data +=3D f'.TH "{args["function"]}" 9 "{args["function"]}" "= {self.man_date}" "Kernel Hacker\'s Manual" LINUX' + "\n" =20 self.data +=3D ".SH NAME\n" @@ -661,11 +647,11 @@ class ManFormat(OutputFormat): parenth =3D "(" post =3D "," =20 - for parameter in parameterlist: - if count =3D=3D len(parameterlist) - 1: + for parameter in args.parameterlist: + if count =3D=3D len(args.parameterlist) - 1: post =3D ");" =20 - dtype =3D args['parametertypes'].get(parameter, "") + dtype =3D args.parametertypes.get(parameter, "") if function_pointer.match(dtype): # Pointer-to-function self.data +=3D f'".BI "{parenth}{function_pointer.group(1)= }" " ") ({function_pointer.group(2)}){post}"' + "\n" @@ -676,14 +662,14 @@ class ManFormat(OutputFormat): count +=3D 1 parenth =3D "" =20 - if parameterlist: + if args.parameterlist: self.data +=3D ".SH ARGUMENTS\n" =20 - for parameter in parameterlist: + for parameter in args.parameterlist: parameter_name =3D re.sub(r'\[.*', '', parameter) =20 self.data +=3D f'.IP "{parameter}" 12' + "\n" - self.output_highlight(parameterdescs.get(parameter_name, "")) + self.output_highlight(args.parameterdescs.get(parameter_name, = "")) =20 for section, text in args.sections.items(): self.data +=3D f'.SH "{section.upper()}"' + "\n" @@ -692,7 +678,6 @@ class ManFormat(OutputFormat): def out_enum(self, fname, name, args): =20 name =3D args.get('enum', '') - parameterlist =3D args.get('parameterlist', []) =20 self.data +=3D f'.TH "{self.modulename}" 9 "enum {args["enum"]}" "= {self.man_date}" "API Manual" LINUX' + "\n" =20 @@ -703,9 +688,9 @@ class ManFormat(OutputFormat): self.data +=3D f"enum {args['enum']}" + " {\n" =20 count =3D 0 - for parameter in parameterlist: + for parameter in args.parameterlist: self.data +=3D f'.br\n.BI " {parameter}"' + "\n" - if count =3D=3D len(parameterlist) - 1: + if count =3D=3D len(args.parameterlist) - 1: self.data +=3D "\n};\n" else: self.data +=3D ", \n.br\n" @@ -714,10 +699,10 @@ class ManFormat(OutputFormat): =20 self.data +=3D ".SH Constants\n" =20 - for parameter in parameterlist: + for parameter in args.parameterlist: parameter_name =3D KernRe(r'\[.*').sub('', parameter) self.data +=3D f'.IP "{parameter}" 12' + "\n" - self.output_highlight(args['parameterdescs'].get(parameter_nam= e, "")) + self.output_highlight(args.parameterdescs.get(parameter_name, = "")) =20 for section, text in args.sections.items(): self.data +=3D f'.SH "{section}"' + "\n" @@ -743,8 +728,6 @@ class ManFormat(OutputFormat): struct_name =3D args.get('struct') purpose =3D args.get('purpose') definition =3D args.get('definition') - parameterlist =3D args.get('parameterlist', []) - parameterdescs =3D args.get('parameterdescs', {}) =20 self.data +=3D f'.TH "{module}" 9 "{struct_type} {struct_name}" "{= self.man_date}" "API Manual" LINUX' + "\n" =20 @@ -760,17 +743,17 @@ class ManFormat(OutputFormat): self.data +=3D f'.BI "{declaration}\n' + "};\n.br\n\n" =20 self.data +=3D ".SH Members\n" - for parameter in parameterlist: + for parameter in args.parameterlist: if parameter.startswith("#"): continue =20 parameter_name =3D re.sub(r"\[.*", "", parameter) =20 - if parameterdescs.get(parameter_name) =3D=3D KernelDoc.undescr= ibed: + if args.parameterdescs.get(parameter_name) =3D=3D KernelDoc.un= described: continue =20 self.data +=3D f'.IP "{parameter}" 12' + "\n" - self.output_highlight(parameterdescs.get(parameter_name)) + self.output_highlight(args.parameterdescs.get(parameter_name)) =20 for section, text in args.sections.items(): self.data +=3D f'.SH "{section}"' + "\n" diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index ffd49f9395ae..298abd260264 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -278,7 +278,9 @@ class KernelDoc: if section in sections and not sections[section].rstrip(): del sections[section] item.set_sections(sections, self.entry.section_start_lines) - + item.set_params(self.entry.parameterlist, self.entry.parameterdesc= s, + self.entry.parametertypes, + self.entry.parameterdesc_start_lines) self.entries.append(item) =20 self.config.log.debug("Output: %s:%s =3D %s", dtype, name, pformat= (args)) @@ -790,10 +792,6 @@ class KernelDoc: self.output_declaration(decl_type, declaration_name, struct=3Ddeclaration_name, definition=3Ddeclaration, - parameterlist=3Dself.entry.parameterlist, - parameterdescs=3Dself.entry.parameterdescs, - parametertypes=3Dself.entry.parametertypes, - parameterdesc_start_lines=3Dself.entry.par= ameterdesc_start_lines, purpose=3Dself.entry.declaration_purpose) =20 def dump_enum(self, ln, proto): @@ -873,9 +871,6 @@ class KernelDoc: =20 self.output_declaration('enum', declaration_name, enum=3Ddeclaration_name, - parameterlist=3Dself.entry.parameterlist, - parameterdescs=3Dself.entry.parameterdescs, - parameterdesc_start_lines=3Dself.entry.par= ameterdesc_start_lines, purpose=3Dself.entry.declaration_purpose) =20 def dump_declaration(self, ln, prototype): @@ -1039,10 +1034,6 @@ class KernelDoc: function=3Ddeclaration_name, typedef=3DTrue, functiontype=3Dreturn_type, - parameterlist=3Dself.entry.parameterli= st, - parameterdescs=3Dself.entry.parameterd= escs, - parametertypes=3Dself.entry.parametert= ypes, - parameterdesc_start_lines=3Dself.entry= .parameterdesc_start_lines, purpose=3Dself.entry.declaration_purpo= se, func_macro=3Dfunc_macro) else: @@ -1050,10 +1041,6 @@ class KernelDoc: function=3Ddeclaration_name, typedef=3DFalse, functiontype=3Dreturn_type, - parameterlist=3Dself.entry.parameterli= st, - parameterdescs=3Dself.entry.parameterd= escs, - parametertypes=3Dself.entry.parametert= ypes, - parameterdesc_start_lines=3Dself.entry= .parameterdesc_start_lines, purpose=3Dself.entry.declaration_purpo= se, func_macro=3Dfunc_macro) =20 @@ -1093,10 +1080,6 @@ class KernelDoc: function=3Ddeclaration_name, typedef=3DTrue, functiontype=3Dreturn_type, - parameterlist=3Dself.entry.parameterli= st, - parameterdescs=3Dself.entry.parameterd= escs, - parametertypes=3Dself.entry.parametert= ypes, - parameterdesc_start_lines=3Dself.entry= .parameterdesc_start_lines, purpose=3Dself.entry.declaration_purpo= se) return =20 --=20 2.49.0 From nobody Wed Oct 8 02:02:17 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 A85141EFFB2; Wed, 2 Jul 2025 22:36: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=1751495767; cv=none; b=hAgJp5OUGDqu54OnraqU8X+3fDf4898thzVerPPUIfcekcWkIKiM1VYoGEmXw2MGFDjV9Wn1Zg/nZeBWkreF6fUw85k95ZpfNhHPStm0xnsaKPRVkkRaI2YqyueKXIqJTdgG4MMbtyuE5Aa/iwhmqwTm8MGuM8JEL0nKYVUqhhU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751495767; c=relaxed/simple; bh=4SkXDuSH5d0MQz0tjUtF3aVxZM9jev/kKFwYIgV3dIA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=eIOLtj6xjVm6uzq5l7ttnfRpuAkeqfkZ6eHW2zGHOUv2sTchdrwc/3AgyTL9ct91aLl4QQ1wNDtasx5wSQgIAUR3kbY5Ywta95/3WmF/gKGPzUWGw2cLje/NpGEtyicqGIU+ucTAZDuDQZqUZxuMZarxLqRmZI3qJGqhICN1wQY= 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=fDE2vn4q; 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="fDE2vn4q" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 0DDDE40ADA DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751495763; bh=60fwhjdRi8LYqWQgY9qP3XX75O6s+2P4dOVrLSNmfcE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=fDE2vn4q9qBS1ON2SEhGrc/RnmgVSXGAEHtowqYvm/kZ2axUEQfKxxldFpGACwJim FjyAoVjxSAonjsKH0W/Vh06yi25GyYWMaoB37RdoKEeaxjtA+M76EKqiqoQMYb5r7H Bmz/q/3skxS3JG6JYImYuExpv2sIxwuIdVBAYMnqwCOsU+9JbB3xxM9pZAoAYdGFZt aOLlYH4g4u3mnuXJU7eXSEBgoQlF7QW+BMqfKhtNQ5dRaXuOdtfIuqKB13nWlAcyG6 op02S3fYe4QhwKftiBxCvjwCdeOo+9IVjXWFth/B+LD0PIvZ9WYQcji4NJEGZC+Is9 pw8gme4R1pOcg== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 0DDDE40ADA; Wed, 2 Jul 2025 22:36:03 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 08/12] docs: kdoc: Regularize the use of the declaration name Date: Wed, 2 Jul 2025 16:35:20 -0600 Message-ID: <20250702223524.231794-9-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250702223524.231794-1-corbet@lwn.net> References: <20250702223524.231794-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" Each declaration type passes through the name in a unique field of the "args" blob - even though we have always just passed the name separately. Get rid of all the weird names and just use the common version. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab Reviewed-by: Yanteng Si --- scripts/lib/kdoc/kdoc_output.py | 39 +++++++++++++-------------------- scripts/lib/kdoc/kdoc_parser.py | 6 ----- 2 files changed, 15 insertions(+), 30 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_output.py b/scripts/lib/kdoc/kdoc_output= .py index d6f4d9e7173b..8a31b637ffd2 100644 --- a/scripts/lib/kdoc/kdoc_output.py +++ b/scripts/lib/kdoc/kdoc_output.py @@ -367,11 +367,11 @@ class RestFormat(OutputFormat): =20 func_macro =3D args.get('func_macro', False) if func_macro: - signature =3D args['function'] + signature =3D name else: if args.get('functiontype'): signature =3D args['functiontype'] + " " - signature +=3D args['function'] + " (" + signature +=3D name + " (" =20 ln =3D args.get('declaration_start_line', 0) count =3D 0 @@ -391,7 +391,7 @@ class RestFormat(OutputFormat): =20 self.print_lineno(ln) if args.get('typedef') or not args.get('functiontype'): - self.data +=3D f".. c:macro:: {args['function']}\n\n" + self.data +=3D f".. c:macro:: {name}\n\n" =20 if args.get('typedef'): self.data +=3D " **Typedef**: " @@ -445,7 +445,6 @@ class RestFormat(OutputFormat): def out_enum(self, fname, name, args): =20 oldprefix =3D self.lineprefix - name =3D args.get('enum', '') ln =3D args.get('declaration_start_line', 0) =20 self.data +=3D f"\n\n.. c:enum:: {name}\n\n" @@ -475,7 +474,6 @@ class RestFormat(OutputFormat): def out_typedef(self, fname, name, args): =20 oldprefix =3D self.lineprefix - name =3D args.get('typedef', '') ln =3D args.get('declaration_start_line', 0) =20 self.data +=3D f"\n\n.. c:type:: {name}\n\n" @@ -492,7 +490,6 @@ class RestFormat(OutputFormat): =20 def out_struct(self, fname, name, args): =20 - name =3D args.get('struct', "") purpose =3D args.get('purpose', "") declaration =3D args.get('definition', "") dtype =3D args.get('type', "struct") @@ -632,16 +629,16 @@ class ManFormat(OutputFormat): def out_function(self, fname, name, args): """output function in man""" =20 - self.data +=3D f'.TH "{args["function"]}" 9 "{args["function"]}" "= {self.man_date}" "Kernel Hacker\'s Manual" LINUX' + "\n" + self.data +=3D f'.TH "{name}" 9 "{name}" "{self.man_date}" "Kernel= Hacker\'s Manual" LINUX' + "\n" =20 self.data +=3D ".SH NAME\n" - self.data +=3D f"{args['function']} \\- {args['purpose']}\n" + self.data +=3D f"{name} \\- {args['purpose']}\n" =20 self.data +=3D ".SH SYNOPSIS\n" if args.get('functiontype', ''): - self.data +=3D f'.B "{args["functiontype"]}" {args["function"]= }' + "\n" + self.data +=3D f'.B "{args["functiontype"]}" {name}' + "\n" else: - self.data +=3D f'.B "{args["function"]}' + "\n" + self.data +=3D f'.B "{name}' + "\n" =20 count =3D 0 parenth =3D "(" @@ -676,16 +673,13 @@ class ManFormat(OutputFormat): self.output_highlight(text) =20 def out_enum(self, fname, name, args): - - name =3D args.get('enum', '') - - self.data +=3D f'.TH "{self.modulename}" 9 "enum {args["enum"]}" "= {self.man_date}" "API Manual" LINUX' + "\n" + self.data +=3D f'.TH "{self.modulename}" 9 "enum {name}" "{self.ma= n_date}" "API Manual" LINUX' + "\n" =20 self.data +=3D ".SH NAME\n" - self.data +=3D f"enum {args['enum']} \\- {args['purpose']}\n" + self.data +=3D f"enum {name} \\- {args['purpose']}\n" =20 self.data +=3D ".SH SYNOPSIS\n" - self.data +=3D f"enum {args['enum']}" + " {\n" + self.data +=3D f"enum {name}" + " {\n" =20 count =3D 0 for parameter in args.parameterlist: @@ -710,13 +704,12 @@ class ManFormat(OutputFormat): =20 def out_typedef(self, fname, name, args): module =3D self.modulename - typedef =3D args.get('typedef') purpose =3D args.get('purpose') =20 - self.data +=3D f'.TH "{module}" 9 "{typedef}" "{self.man_date}" "A= PI Manual" LINUX' + "\n" + self.data +=3D f'.TH "{module}" 9 "{name}" "{self.man_date}" "API = Manual" LINUX' + "\n" =20 self.data +=3D ".SH NAME\n" - self.data +=3D f"typedef {typedef} \\- {purpose}\n" + self.data +=3D f"typedef {name} \\- {purpose}\n" =20 for section, text in args.sections.items(): self.data +=3D f'.SH "{section}"' + "\n" @@ -724,22 +717,20 @@ class ManFormat(OutputFormat): =20 def out_struct(self, fname, name, args): module =3D self.modulename - struct_type =3D args.get('type') - struct_name =3D args.get('struct') purpose =3D args.get('purpose') definition =3D args.get('definition') =20 - self.data +=3D f'.TH "{module}" 9 "{struct_type} {struct_name}" "{= self.man_date}" "API Manual" LINUX' + "\n" + self.data +=3D f'.TH "{module}" 9 "{args.type} {name}" "{self.man_= date}" "API Manual" LINUX' + "\n" =20 self.data +=3D ".SH NAME\n" - self.data +=3D f"{struct_type} {struct_name} \\- {purpose}\n" + self.data +=3D f"{args.type} {name} \\- {purpose}\n" =20 # Replace tabs with two spaces and handle newlines declaration =3D definition.replace("\t", " ") declaration =3D KernRe(r"\n").sub('"\n.br\n.BI "', declaration) =20 self.data +=3D ".SH SYNOPSIS\n" - self.data +=3D f"{struct_type} {struct_name} " + "{" + "\n.br\n" + self.data +=3D f"{args.type} {name} " + "{" + "\n.br\n" self.data +=3D f'.BI "{declaration}\n' + "};\n.br\n\n" =20 self.data +=3D ".SH Members\n" diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 298abd260264..6e35e508608b 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -790,7 +790,6 @@ class KernelDoc: level +=3D 1 =20 self.output_declaration(decl_type, declaration_name, - struct=3Ddeclaration_name, definition=3Ddeclaration, purpose=3Dself.entry.declaration_purpose) =20 @@ -870,7 +869,6 @@ class KernelDoc: f"Excess enum value '%{k}' description in '{= declaration_name}'") =20 self.output_declaration('enum', declaration_name, - enum=3Ddeclaration_name, purpose=3Dself.entry.declaration_purpose) =20 def dump_declaration(self, ln, prototype): @@ -1031,14 +1029,12 @@ class KernelDoc: =20 if 'typedef' in return_type: self.output_declaration(decl_type, declaration_name, - function=3Ddeclaration_name, typedef=3DTrue, functiontype=3Dreturn_type, purpose=3Dself.entry.declaration_purpo= se, func_macro=3Dfunc_macro) else: self.output_declaration(decl_type, declaration_name, - function=3Ddeclaration_name, typedef=3DFalse, functiontype=3Dreturn_type, purpose=3Dself.entry.declaration_purpo= se, @@ -1077,7 +1073,6 @@ class KernelDoc: self.create_parameter_list(ln, decl_type, args, ',', declarati= on_name) =20 self.output_declaration(decl_type, declaration_name, - function=3Ddeclaration_name, typedef=3DTrue, functiontype=3Dreturn_type, purpose=3Dself.entry.declaration_purpo= se) @@ -1099,7 +1094,6 @@ class KernelDoc: return =20 self.output_declaration('typedef', declaration_name, - typedef=3Ddeclaration_name, purpose=3Dself.entry.declaration_purpo= se) return =20 --=20 2.49.0 From nobody Wed Oct 8 02:02:17 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 8979B24886A; Wed, 2 Jul 2025 22:36:07 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751495769; cv=none; b=pVoxcJfiDMFtPDLh7/VBOl2jsW819WlHjh6ktlTXoGxgW1DnNkyZZaXrMQ55WiXJIqIz8FctluRHDUxziFZu2QElDNE9xx+4lPm29ef0EiUBTDcPZAqV9vrFZkaRftGaSIJ2CzLcNLaSaKhilW5ISkiYg8WJcujfkdcjeAQUpRU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751495769; c=relaxed/simple; bh=YwQmmM22mJD5uF6bQs9i5TfzwwX4HApOUYGTGeMFVIc=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Oz3XfKHQywN7ok59bMFvB+s/Q4sc+wJbHh3gJtpOP5cV9B6EKwoRj5s22ehq5j7C5iePrvZu6Rb4QMW5FDcs83JMN2UL+bACZvl1Ig0XxUdBaTa2STzCd6E7mhV4Q+6WY28iBlaXmG3EZIAV8dCeAgD9zOoCLvBQNqNsGM8fVWc= 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=HNkt6a1e; 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="HNkt6a1e" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 91B0B40ADB DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751495764; bh=RT1pjY34zsbO6cT0rpZcZaAuDKckUPNC0BOielZL+3U=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=HNkt6a1el2p4Cy0/fYnf2kL+gJE4punHq+xo16uU+yLQKR2Q61SqzFKrAwXDGXSBI 7/nvFZ5o6ZA86mvbVFpu04bXZU93hzdF8u/mBQ1Lh0vEIknD7b8dpA/seILqH4z+j9 bW/Rovu47J++dHUzHg+XoAD2CAsCkGhKo7sflDQB0+r5FEHzAoocWXEBVfENlzmRUQ RhEZ7OOGlBD6WlyAGod7+BSvpeASeo1Hj/QByo+8DjAG8N1YFTcJsZmwGsxeHcXz6q jWus+La1eC/nNVdPDRjZX0QFImytLw5H9bGnW9olVu/6qZX68sW1zWL1FWpHvnt04t I9wmCVJaACVcQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 91B0B40ADB; Wed, 2 Jul 2025 22:36:03 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 09/12] docs: kdoc: straighten up dump_declaration() Date: Wed, 2 Jul 2025 16:35:21 -0600 Message-ID: <20250702223524.231794-10-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250702223524.231794-1-corbet@lwn.net> References: <20250702223524.231794-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" Get rid of the excess "return" statements in dump_declaration(), along with a line of never-executed dead code. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab Reviewed-by: Yanteng Si --- scripts/lib/kdoc/kdoc_parser.py | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 6e35e508608b..7191fa94e17a 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -878,18 +878,13 @@ class KernelDoc: =20 if self.entry.decl_type =3D=3D "enum": self.dump_enum(ln, prototype) - return - - if self.entry.decl_type =3D=3D "typedef": + elif self.entry.decl_type =3D=3D "typedef": self.dump_typedef(ln, prototype) - return - - if self.entry.decl_type in ["union", "struct"]: + elif self.entry.decl_type in ["union", "struct"]: self.dump_struct(ln, prototype) - return - - self.output_declaration(self.entry.decl_type, prototype, - entry=3Dself.entry) + else: + # This would be a bug + self.emit_message(ln, f'Unknown declaration type: {self.entry.= decl_type}') =20 def dump_function(self, ln, prototype): """ --=20 2.49.0 From nobody Wed Oct 8 02:02:17 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 89888248F5F; Wed, 2 Jul 2025 22:36:07 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751495769; cv=none; b=dPGH+MG7liYQAwfU7UEXzLDuDl1eJ1v2DqzpxvBr4e02NmKU+Qrts98MG4jT4wUNv61EgLcH9ME63JWwYa66fREllwWJn/RKGnVb62QDisl0eF/lhvuhfy8IC15Z1dT+7FtLGctCT4fBnfA007k39hpigCcdL8UjzPsxH6VTtX4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751495769; c=relaxed/simple; bh=BynowONsB9loA0lfjkoAwOWy03aovuUqcqYge5s+3G4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=KWpsW84rlUi95Bw4jNVq/DGbcIZnb8ULtLbv+asA99HTT2IiOPjHJFC2A0Y0HG2/dYxZHnAE55m54H7w9SvnrwKzqYJQtzZ93HDEY+wDIkP7iKSB8KAKFjKshnFNeNvNrmgn7aR860PEicLnYU0c+9OBrlIzo55Hv0O4oEt22tY= 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=brFmjVEt; 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="brFmjVEt" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 2D40840ADC DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751495764; bh=dNof+AXeq/f+pu3hjZOO4w64OTws2zFcSf5JnVShQt0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=brFmjVEt4C8AJqGYv2pzslIf+zzGuV6CdyI85lQDz6NfqXNftoJdw8GQ+K3xsFM+e BygqL5k0Hf4Zu53LWRLCYHkHsztRiCZuGm5MBTeiwzS0nEBk/C/MiwMicZNKToaV1v Dc5gpX6x9o0c6x3UEfODUENrbsTkfWCCwhO5WJGJOkp7s+Eb+ZV/UZ3zTvUXmHuTjX 2zDKAaKROaiPj8r39zSM/uz5ebPh/qfJHP5WSAjwn4UTISDwA24lhBztEXre3L7fSG +aHedvh5QuCxJIC0Tx8ArHN3D9VpDdUyUUftJQ7CIfNQE0f1dijB63uqkciylJEf9+ Y8WfOvX66MahQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 2D40840ADC; Wed, 2 Jul 2025 22:36:04 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 10/12] docs: kdoc: directly access the always-there KdocItem fields Date: Wed, 2 Jul 2025 16:35:22 -0600 Message-ID: <20250702223524.231794-11-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250702223524.231794-1-corbet@lwn.net> References: <20250702223524.231794-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" They are part of the interface, so use them directly. This allows the removal of the transitional __dict__ hack in KdocItem. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab Reviewed-by: Yanteng Si --- scripts/lib/kdoc/kdoc_item.py | 5 +---- scripts/lib/kdoc/kdoc_output.py | 16 +++++++--------- 2 files changed, 8 insertions(+), 13 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_item.py b/scripts/lib/kdoc/kdoc_item.py index 51e8669b9a6e..807290678984 100644 --- a/scripts/lib/kdoc/kdoc_item.py +++ b/scripts/lib/kdoc/kdoc_item.py @@ -20,10 +20,7 @@ class KdocItem: self.other_stuff =3D other_stuff =20 def get(self, key, default =3D None): - ret =3D self.other_stuff.get(key, default) - if ret =3D=3D default: - return self.__dict__.get(key, default) - return ret + return self.other_stuff.get(key, default) =20 def __getitem__(self, key): return self.get(key) diff --git a/scripts/lib/kdoc/kdoc_output.py b/scripts/lib/kdoc/kdoc_output= .py index 8a31b637ffd2..ea8914537ba0 100644 --- a/scripts/lib/kdoc/kdoc_output.py +++ b/scripts/lib/kdoc/kdoc_output.py @@ -124,9 +124,7 @@ class OutputFormat: Output warnings for identifiers that will be displayed. """ =20 - warnings =3D args.get('warnings', []) - - for log_msg in warnings: + for log_msg in args.warnings: self.config.warning(log_msg) =20 def check_doc(self, name, args): @@ -184,7 +182,7 @@ class OutputFormat: =20 self.data =3D "" =20 - dtype =3D args.get('type', "") + dtype =3D args.type =20 if dtype =3D=3D "doc": self.out_doc(fname, name, args) @@ -373,7 +371,7 @@ class RestFormat(OutputFormat): signature =3D args['functiontype'] + " " signature +=3D name + " (" =20 - ln =3D args.get('declaration_start_line', 0) + ln =3D args.declaration_start_line count =3D 0 for parameter in args.parameterlist: if count !=3D 0: @@ -445,7 +443,7 @@ class RestFormat(OutputFormat): def out_enum(self, fname, name, args): =20 oldprefix =3D self.lineprefix - ln =3D args.get('declaration_start_line', 0) + ln =3D args.declaration_start_line =20 self.data +=3D f"\n\n.. c:enum:: {name}\n\n" =20 @@ -474,7 +472,7 @@ class RestFormat(OutputFormat): def out_typedef(self, fname, name, args): =20 oldprefix =3D self.lineprefix - ln =3D args.get('declaration_start_line', 0) + ln =3D args.declaration_start_line =20 self.data +=3D f"\n\n.. c:type:: {name}\n\n" =20 @@ -492,8 +490,8 @@ class RestFormat(OutputFormat): =20 purpose =3D args.get('purpose', "") declaration =3D args.get('definition', "") - dtype =3D args.get('type', "struct") - ln =3D args.get('declaration_start_line', 0) + dtype =3D args.type + ln =3D args.declaration_start_line =20 self.data +=3D f"\n\n.. c:{dtype}:: {name}\n\n" =20 --=20 2.49.0 From nobody Wed Oct 8 02:02:17 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 897142472A6; Wed, 2 Jul 2025 22:36:07 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751495769; cv=none; b=eNyBBtJ0TKsX9ftFSg4u9lKwrVCqoZkf62tGQCkV9Ww5xlbkL0SiyQ1cxlny7R+53ZPmjMfAEdqXpi7kSXlSADv1GbdH2e7LUItuwEnUuFQ1asjgrQynLT6HYdpu/3PzCASCbUYBIaVNCwAVIl8uzRleyBBDFry2fZ45jcSKpaA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751495769; c=relaxed/simple; bh=gydrlw3jSIF8YBncgRSZIy922KgoW02e3WJd1Tq6HDY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=FszpIEpr2B61dT8Akz0YpZFTPdNSBLZgrA0zgyunMR1IracBuLM9HjCEjDPlXt/ynXHY+CRbTznruE+nOvdBVY+sGZmlKjhXSxi1xdE32SL2V2gDY0QHXAsIcAvznBvryayYJBCcw0JnqgGM1yKTyb1Ezhs2mi5IUyf0k0hxrSM= 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=Lsh8jnTA; 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="Lsh8jnTA" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net B4EDB40ADD DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751495765; bh=lVh5lPm+56xQ1oIpXv6wt5iACADHmHN49eSQAKWz0FA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Lsh8jnTAVTKu1akXjIUfevRG0Um/hO57sMsNrHG9D2oBxPU43gpuIayCOsrk4f8SD HTOf3K+4JixahtUGX4XX8SYZgnoeTJrjgTnOQGvLqbu/+YCB15VRh+/cBC4faVb5yL Q2VYl7B8flEhCBxoO6ls6x3foeOmCYpAq8viRX7ALW9DGXugKRlZxx4UyDT9A9ZKjU qYcnfVk0E00bCz1538wjXNKpxqlwBQfsDdfbCsZ6TW6fpgpQJWDcjQebsu9BiR67bu baOHDEf/6TWB3GlniW1EqjK5dWxdQgR6zu/iD7MZN0gKDpzmB93bs48aVeei7gGGfY RePL8I0g4NWVA== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id B4EDB40ADD; Wed, 2 Jul 2025 22:36:04 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 11/12] docs: kdoc: clean up check_sections() Date: Wed, 2 Jul 2025 16:35:23 -0600 Message-ID: <20250702223524.231794-12-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250702223524.231794-1-corbet@lwn.net> References: <20250702223524.231794-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.sectcheck is just a duplicate of our list of sections that is only passed to check_sections(); its main purpose seems to be to avoid checking the special named sections. Rework check_sections() to not use that field (which is then deleted), tocheck for the known sections directly, and tighten up the logic in general. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab Reviewed-by: Yanteng Si --- scripts/lib/kdoc/kdoc_parser.py | 31 +++++++++++-------------------- 1 file changed, 11 insertions(+), 20 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 7191fa94e17a..fdde14b045fe 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -42,9 +42,11 @@ doc_decl =3D doc_com + KernRe(r'(\w+)', cache=3DFalse) # @{section-name}: # while trying to not match literal block starts like "example::" # +known_section_names =3D 'description|context|returns?|notes?|examples?' +known_sections =3D KernRe(known_section_names, flags =3D re.I) doc_sect =3D doc_com + \ - KernRe(r'\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|no= tes?|examples?)\s*:([^:].*)?$', - flags=3Dre.I, cache=3DFalse) + KernRe(r'\s*(\@[.\w]+|\@\.\.\.|' + known_section_names + r')\s*:([^:].= *)?$', + flags=3Dre.I, cache=3DFalse) =20 doc_content =3D doc_com_body + KernRe(r'(.*)', cache=3DFalse) doc_inline_start =3D KernRe(r'^\s*/\*\*\s*$', cache=3DFalse) @@ -115,7 +117,6 @@ class KernelEntry: self.config =3D config =20 self._contents =3D [] - self.sectcheck =3D "" self.prototype =3D "" =20 self.warnings =3D [] @@ -187,7 +188,6 @@ class KernelEntry: self.parameterdescs[name] =3D contents self.parameterdesc_start_lines[name] =3D self.new_start_line =20 - self.sectcheck +=3D name + " " self.new_start_line =3D 0 =20 else: @@ -478,29 +478,20 @@ class KernelDoc: self.push_parameter(ln, decl_type, param, dtype, arg, declaration_name) =20 - def check_sections(self, ln, decl_name, decl_type, sectcheck): + def check_sections(self, ln, decl_name, decl_type): """ Check for errors inside sections, emitting warnings if not found parameters are described. """ - - sects =3D sectcheck.split() - - for sx in range(len(sects)): # pylint: disable=3D= C0200 - err =3D True - for param in self.entry.parameterlist: - if param =3D=3D sects[sx]: - err =3D False - break - - if err: + for section in self.entry.sections: + if section not in self.entry.parameterlist and \ + not known_sections.search(section): if decl_type =3D=3D 'function': dname =3D f"{decl_type} parameter" else: dname =3D f"{decl_type} member" - self.emit_msg(ln, - f"Excess {dname} '{sects[sx]}' description i= n '{decl_name}'") + f"Excess {dname} '{section}' description in = '{decl_name}'") =20 def check_return_section(self, ln, declaration_name, return_type): """ @@ -754,7 +745,7 @@ class KernelDoc: =20 self.create_parameter_list(ln, decl_type, members, ';', declaration_name) - self.check_sections(ln, declaration_name, decl_type, self.entry.se= ctcheck) + self.check_sections(ln, declaration_name, decl_type) =20 # Adjust declaration for better display declaration =3D KernRe(r'([\{;])').sub(r'\1\n', declaration) @@ -1018,7 +1009,7 @@ class KernelDoc: f"expecting prototype for {self.entry.identifier= }(). Prototype was for {declaration_name}() instead") return =20 - self.check_sections(ln, declaration_name, "function", self.entry.s= ectcheck) + self.check_sections(ln, declaration_name, "function") =20 self.check_return_section(ln, declaration_name, return_type) =20 --=20 2.49.0 From nobody Wed Oct 8 02:02:17 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 89820248893; Wed, 2 Jul 2025 22:36:07 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751495769; cv=none; b=MbBc3p85fKEgQ6f8mkavx+T0/H7Cd6U1XR+aBEF28cSWR7LsHoJu9Xp6mqN3v89rZLrUR5XHRAOohI4iaVxcKtqowTONnPeyiEXWCnehHDQr2aIKY9ON1SMwMyzc/+VRC5+7JujTvYz9FGAfoYJfmjZbgCN5hIimFfN7wOFdRP4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751495769; c=relaxed/simple; bh=yK8y5N6gNclPxjmJnRZgewzX2UW9/j0lFf3u2z072sg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=mo/yR8ly+i1B8DdnZgH+Q/TolHUszv+Tt6OX+wBg3sXl4N9+mWH/K3nzz2FG0z71QQDKZNfBvcusZh9pIPtw6HifinNzx2YUGkywi0e44V/hXqTJHjqBcsG+jjo1/2oooYyYJ6hlhYYE33pER8DxUOrV09TK/WUa6oD3Fn7rsBc= 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=GMoGaT0d; 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="GMoGaT0d" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 45C2240ADE DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1751495765; bh=yzUoekRs6KviceLIn0+5Pv5CjlxCW0YQP/vVgcegNhw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=GMoGaT0dAJZXFUd906FVWEBe3Z2I8AESUza31qgaqgHe1iIWNyFzbNSkByWyZumCP qdTGapEjLEvSskVvAEeAPmyzrBVZY5Lh2JnQ+titJWrmDWe6HGTlrLLh/3i1nAxa+8 YmA9muPlql9Gb82MuLhWI0mU5z+EtyQSxlmDVss6EGE9gyo5V2z+RQO0JGQ/VRkD6o NvKVkRPmvYCrUk9jkd6cj7a+1Yah6YXn1SyxjREQ4RQafHEkrQslVgXVu+s1Jze7ot ESIvOd72+UX3Fc5eJVQg6VAtD6nAfT9Rweo/OEoGnBoX1s3CZMfQ+l3+Gzj4AdKsi9 /sYsKx/V1p3GA== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 45C2240ADE; Wed, 2 Jul 2025 22:36:05 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 12/12] docs: kdoc: Improve the output text accumulation Date: Wed, 2 Jul 2025 16:35:24 -0600 Message-ID: <20250702223524.231794-13-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250702223524.231794-1-corbet@lwn.net> References: <20250702223524.231794-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" Building strings with repeated concatenation is somewhat inefficient in Python; it is better to make a list and glom them all together at the end. Add a small set of methods to the OutputFormat superclass to manage the output string, and use them throughout. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab Reviewed-by: Yanteng Si --- scripts/lib/kdoc/kdoc_output.py | 185 +++++++++++++++++--------------- 1 file changed, 98 insertions(+), 87 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_output.py b/scripts/lib/kdoc/kdoc_output= .py index ea8914537ba0..d4aabdaa9c51 100644 --- a/scripts/lib/kdoc/kdoc_output.py +++ b/scripts/lib/kdoc/kdoc_output.py @@ -73,7 +73,19 @@ class OutputFormat: self.config =3D None self.no_doc_sections =3D False =20 - self.data =3D "" + # + # Accumulation and management of the output text. + # + def reset_output(self): + self._output =3D [] + + def emit(self, text): + """Add a string to out output text""" + self._output.append(text) + + def output(self): + """Obtain the accumulated output text""" + return ''.join(self._output) =20 def set_config(self, config): """ @@ -180,32 +192,31 @@ class OutputFormat: Handles a single entry from kernel-doc parser """ =20 - self.data =3D "" - + self.reset_output() dtype =3D args.type =20 if dtype =3D=3D "doc": self.out_doc(fname, name, args) - return self.data + return self.output() =20 if not self.check_declaration(dtype, name, args): - return self.data + return self.output() =20 if dtype =3D=3D "function": self.out_function(fname, name, args) - return self.data + return self.output() =20 if dtype =3D=3D "enum": self.out_enum(fname, name, args) - return self.data + return self.output() =20 if dtype =3D=3D "typedef": self.out_typedef(fname, name, args) - return self.data + return self.output() =20 if dtype in ["struct", "union"]: self.out_struct(fname, name, args) - return self.data + return self.output() =20 # Warn if some type requires an output logic self.config.log.warning("doesn't now how to output '%s' block", @@ -274,7 +285,7 @@ class RestFormat(OutputFormat): =20 if self.enable_lineno and ln is not None: ln +=3D 1 - self.data +=3D f".. LINENO {ln}\n" + self.emit(f".. LINENO {ln}\n") =20 def output_highlight(self, args): """ @@ -326,7 +337,7 @@ class RestFormat(OutputFormat): =20 # Print the output with the line prefix for line in output.strip("\n").split("\n"): - self.data +=3D self.lineprefix + line + "\n" + self.emit(self.lineprefix + line + "\n") =20 def out_section(self, args, out_docblock=3DFalse): """ @@ -343,15 +354,15 @@ class RestFormat(OutputFormat): =20 if out_docblock: if not self.out_mode =3D=3D self.OUTPUT_INCLUDE: - self.data +=3D f".. _{section}:\n\n" - self.data +=3D f'{self.lineprefix}**{section}**\n\n' + self.emit(f".. _{section}:\n\n") + self.emit(f'{self.lineprefix}**{section}**\n\n') else: - self.data +=3D f'{self.lineprefix}**{section}**\n\n' + self.emit(f'{self.lineprefix}**{section}**\n\n') =20 self.print_lineno(args.section_start_lines.get(section, 0)) self.output_highlight(text) - self.data +=3D "\n" - self.data +=3D "\n" + self.emit("\n") + self.emit("\n") =20 def out_doc(self, fname, name, args): if not self.check_doc(name, args): @@ -389,41 +400,41 @@ class RestFormat(OutputFormat): =20 self.print_lineno(ln) if args.get('typedef') or not args.get('functiontype'): - self.data +=3D f".. c:macro:: {name}\n\n" + self.emit(f".. c:macro:: {name}\n\n") =20 if args.get('typedef'): - self.data +=3D " **Typedef**: " + self.emit(" **Typedef**: ") self.lineprefix =3D "" self.output_highlight(args.get('purpose', "")) - self.data +=3D "\n\n**Syntax**\n\n" - self.data +=3D f" ``{signature}``\n\n" + self.emit("\n\n**Syntax**\n\n") + self.emit(f" ``{signature}``\n\n") else: - self.data +=3D f"``{signature}``\n\n" + self.emit(f"``{signature}``\n\n") else: - self.data +=3D f".. c:function:: {signature}\n\n" + self.emit(f".. c:function:: {signature}\n\n") =20 if not args.get('typedef'): self.print_lineno(ln) self.lineprefix =3D " " self.output_highlight(args.get('purpose', "")) - self.data +=3D "\n" + self.emit("\n") =20 # Put descriptive text into a container (HTML
) to help set # function prototypes apart self.lineprefix =3D " " =20 if args.parameterlist: - self.data +=3D ".. container:: kernelindent\n\n" - self.data +=3D f"{self.lineprefix}**Parameters**\n\n" + self.emit(".. container:: kernelindent\n\n") + self.emit(f"{self.lineprefix}**Parameters**\n\n") =20 for parameter in args.parameterlist: parameter_name =3D KernRe(r'\[.*').sub('', parameter) dtype =3D args.parametertypes.get(parameter, "") =20 if dtype: - self.data +=3D f"{self.lineprefix}``{dtype}``\n" + self.emit(f"{self.lineprefix}``{dtype}``\n") else: - self.data +=3D f"{self.lineprefix}``{parameter}``\n" + self.emit(f"{self.lineprefix}``{parameter}``\n") =20 self.print_lineno(args.parameterdesc_start_lines.get(parameter= _name, 0)) =20 @@ -432,9 +443,9 @@ class RestFormat(OutputFormat): args.parameterdescs[parameter_name] !=3D KernelDoc.undescri= bed: =20 self.output_highlight(args.parameterdescs[parameter_name]) - self.data +=3D "\n" + self.emit("\n") else: - self.data +=3D f"{self.lineprefix}*undescribed*\n\n" + self.emit(f"{self.lineprefix}*undescribed*\n\n") self.lineprefix =3D " " =20 self.out_section(args) @@ -445,26 +456,26 @@ class RestFormat(OutputFormat): oldprefix =3D self.lineprefix ln =3D args.declaration_start_line =20 - self.data +=3D f"\n\n.. c:enum:: {name}\n\n" + self.emit(f"\n\n.. c:enum:: {name}\n\n") =20 self.print_lineno(ln) self.lineprefix =3D " " self.output_highlight(args.get('purpose', '')) - self.data +=3D "\n" + self.emit("\n") =20 - self.data +=3D ".. container:: kernelindent\n\n" + self.emit(".. container:: kernelindent\n\n") outer =3D self.lineprefix + " " self.lineprefix =3D outer + " " - self.data +=3D f"{outer}**Constants**\n\n" + self.emit(f"{outer}**Constants**\n\n") =20 for parameter in args.parameterlist: - self.data +=3D f"{outer}``{parameter}``\n" + self.emit(f"{outer}``{parameter}``\n") =20 if args.parameterdescs.get(parameter, '') !=3D KernelDoc.undes= cribed: self.output_highlight(args.parameterdescs[parameter]) else: - self.data +=3D f"{self.lineprefix}*undescribed*\n\n" - self.data +=3D "\n" + self.emit(f"{self.lineprefix}*undescribed*\n\n") + self.emit("\n") =20 self.lineprefix =3D oldprefix self.out_section(args) @@ -474,14 +485,14 @@ class RestFormat(OutputFormat): oldprefix =3D self.lineprefix ln =3D args.declaration_start_line =20 - self.data +=3D f"\n\n.. c:type:: {name}\n\n" + self.emit(f"\n\n.. c:type:: {name}\n\n") =20 self.print_lineno(ln) self.lineprefix =3D " " =20 self.output_highlight(args.get('purpose', '')) =20 - self.data +=3D "\n" + self.emit("\n") =20 self.lineprefix =3D oldprefix self.out_section(args) @@ -493,7 +504,7 @@ class RestFormat(OutputFormat): dtype =3D args.type ln =3D args.declaration_start_line =20 - self.data +=3D f"\n\n.. c:{dtype}:: {name}\n\n" + self.emit(f"\n\n.. c:{dtype}:: {name}\n\n") =20 self.print_lineno(ln) =20 @@ -501,20 +512,20 @@ class RestFormat(OutputFormat): self.lineprefix +=3D " " =20 self.output_highlight(purpose) - self.data +=3D "\n" + self.emit("\n") =20 - self.data +=3D ".. container:: kernelindent\n\n" - self.data +=3D f"{self.lineprefix}**Definition**::\n\n" + self.emit(".. container:: kernelindent\n\n") + self.emit(f"{self.lineprefix}**Definition**::\n\n") =20 self.lineprefix =3D self.lineprefix + " " =20 declaration =3D declaration.replace("\t", self.lineprefix) =20 - self.data +=3D f"{self.lineprefix}{dtype} {name}" + ' {' + "\n" - self.data +=3D f"{declaration}{self.lineprefix}" + "};\n\n" + self.emit(f"{self.lineprefix}{dtype} {name}" + ' {' + "\n") + self.emit(f"{declaration}{self.lineprefix}" + "};\n\n") =20 self.lineprefix =3D " " - self.data +=3D f"{self.lineprefix}**Members**\n\n" + self.emit(f"{self.lineprefix}**Members**\n\n") for parameter in args.parameterlist: if not parameter or parameter.startswith("#"): continue @@ -526,15 +537,15 @@ class RestFormat(OutputFormat): =20 self.print_lineno(args.parameterdesc_start_lines.get(parameter= _name, 0)) =20 - self.data +=3D f"{self.lineprefix}``{parameter}``\n" + self.emit(f"{self.lineprefix}``{parameter}``\n") =20 self.lineprefix =3D " " self.output_highlight(args.parameterdescs[parameter_name]) self.lineprefix =3D " " =20 - self.data +=3D "\n" + self.emit("\n") =20 - self.data +=3D "\n" + self.emit("\n") =20 self.lineprefix =3D oldprefix self.out_section(args) @@ -610,33 +621,33 @@ class ManFormat(OutputFormat): continue =20 if line[0] =3D=3D ".": - self.data +=3D "\\&" + line + "\n" + self.emit("\\&" + line + "\n") else: - self.data +=3D line + "\n" + self.emit(line + "\n") =20 def out_doc(self, fname, name, args): 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" + self.emit(f'.TH "{self.modulename}" 9 "{self.modulename}" "{self.m= an_date}" "API Manual" LINUX' + "\n") =20 for section, text in args.sections.items(): - self.data +=3D f'.SH "{section}"' + "\n" + self.emit(f'.SH "{section}"' + "\n") self.output_highlight(text) =20 def out_function(self, fname, name, args): """output function in man""" =20 - self.data +=3D f'.TH "{name}" 9 "{name}" "{self.man_date}" "Kernel= Hacker\'s Manual" LINUX' + "\n" + self.emit(f'.TH "{name}" 9 "{name}" "{self.man_date}" "Kernel Hack= er\'s Manual" LINUX' + "\n") =20 - self.data +=3D ".SH NAME\n" - self.data +=3D f"{name} \\- {args['purpose']}\n" + self.emit(".SH NAME\n") + self.emit(f"{name} \\- {args['purpose']}\n") =20 - self.data +=3D ".SH SYNOPSIS\n" + self.emit(".SH SYNOPSIS\n") if args.get('functiontype', ''): - self.data +=3D f'.B "{args["functiontype"]}" {name}' + "\n" + self.emit(f'.B "{args["functiontype"]}" {name}' + "\n") else: - self.data +=3D f'.B "{name}' + "\n" + self.emit(f'.B "{name}' + "\n") =20 count =3D 0 parenth =3D "(" @@ -649,68 +660,68 @@ class ManFormat(OutputFormat): dtype =3D args.parametertypes.get(parameter, "") if function_pointer.match(dtype): # Pointer-to-function - self.data +=3D f'".BI "{parenth}{function_pointer.group(1)= }" " ") ({function_pointer.group(2)}){post}"' + "\n" + self.emit(f'".BI "{parenth}{function_pointer.group(1)}" " = ") ({function_pointer.group(2)}){post}"' + "\n") else: dtype =3D KernRe(r'([^\*])$').sub(r'\1 ', dtype) =20 - self.data +=3D f'.BI "{parenth}{dtype}" "{post}"' + "\n" + self.emit(f'.BI "{parenth}{dtype}" "{post}"' + "\n") count +=3D 1 parenth =3D "" =20 if args.parameterlist: - self.data +=3D ".SH ARGUMENTS\n" + self.emit(".SH ARGUMENTS\n") =20 for parameter in args.parameterlist: parameter_name =3D re.sub(r'\[.*', '', parameter) =20 - self.data +=3D f'.IP "{parameter}" 12' + "\n" + self.emit(f'.IP "{parameter}" 12' + "\n") self.output_highlight(args.parameterdescs.get(parameter_name, = "")) =20 for section, text in args.sections.items(): - self.data +=3D f'.SH "{section.upper()}"' + "\n" + self.emit(f'.SH "{section.upper()}"' + "\n") self.output_highlight(text) =20 def out_enum(self, fname, name, args): - self.data +=3D f'.TH "{self.modulename}" 9 "enum {name}" "{self.ma= n_date}" "API Manual" LINUX' + "\n" + self.emit(f'.TH "{self.modulename}" 9 "enum {name}" "{self.man_dat= e}" "API Manual" LINUX' + "\n") =20 - self.data +=3D ".SH NAME\n" - self.data +=3D f"enum {name} \\- {args['purpose']}\n" + self.emit(".SH NAME\n") + self.emit(f"enum {name} \\- {args['purpose']}\n") =20 - self.data +=3D ".SH SYNOPSIS\n" - self.data +=3D f"enum {name}" + " {\n" + self.emit(".SH SYNOPSIS\n") + self.emit(f"enum {name}" + " {\n") =20 count =3D 0 for parameter in args.parameterlist: - self.data +=3D f'.br\n.BI " {parameter}"' + "\n" + self.emit(f'.br\n.BI " {parameter}"' + "\n") if count =3D=3D len(args.parameterlist) - 1: - self.data +=3D "\n};\n" + self.emit("\n};\n") else: - self.data +=3D ", \n.br\n" + self.emit(", \n.br\n") =20 count +=3D 1 =20 - self.data +=3D ".SH Constants\n" + self.emit(".SH Constants\n") =20 for parameter in args.parameterlist: parameter_name =3D KernRe(r'\[.*').sub('', parameter) - self.data +=3D f'.IP "{parameter}" 12' + "\n" + self.emit(f'.IP "{parameter}" 12' + "\n") self.output_highlight(args.parameterdescs.get(parameter_name, = "")) =20 for section, text in args.sections.items(): - self.data +=3D f'.SH "{section}"' + "\n" + self.emit(f'.SH "{section}"' + "\n") self.output_highlight(text) =20 def out_typedef(self, fname, name, args): module =3D self.modulename purpose =3D args.get('purpose') =20 - self.data +=3D f'.TH "{module}" 9 "{name}" "{self.man_date}" "API = Manual" LINUX' + "\n" + self.emit(f'.TH "{module}" 9 "{name}" "{self.man_date}" "API Manua= l" LINUX' + "\n") =20 - self.data +=3D ".SH NAME\n" - self.data +=3D f"typedef {name} \\- {purpose}\n" + self.emit(".SH NAME\n") + self.emit(f"typedef {name} \\- {purpose}\n") =20 for section, text in args.sections.items(): - self.data +=3D f'.SH "{section}"' + "\n" + self.emit(f'.SH "{section}"' + "\n") self.output_highlight(text) =20 def out_struct(self, fname, name, args): @@ -718,20 +729,20 @@ class ManFormat(OutputFormat): purpose =3D args.get('purpose') definition =3D args.get('definition') =20 - self.data +=3D f'.TH "{module}" 9 "{args.type} {name}" "{self.man_= date}" "API Manual" LINUX' + "\n" + self.emit(f'.TH "{module}" 9 "{args.type} {name}" "{self.man_date}= " "API Manual" LINUX' + "\n") =20 - self.data +=3D ".SH NAME\n" - self.data +=3D f"{args.type} {name} \\- {purpose}\n" + self.emit(".SH NAME\n") + self.emit(f"{args.type} {name} \\- {purpose}\n") =20 # Replace tabs with two spaces and handle newlines declaration =3D definition.replace("\t", " ") declaration =3D KernRe(r"\n").sub('"\n.br\n.BI "', declaration) =20 - self.data +=3D ".SH SYNOPSIS\n" - self.data +=3D f"{args.type} {name} " + "{" + "\n.br\n" - self.data +=3D f'.BI "{declaration}\n' + "};\n.br\n\n" + self.emit(".SH SYNOPSIS\n") + self.emit(f"{args.type} {name} " + "{" + "\n.br\n") + self.emit(f'.BI "{declaration}\n' + "};\n.br\n\n") =20 - self.data +=3D ".SH Members\n" + self.emit(".SH Members\n") for parameter in args.parameterlist: if parameter.startswith("#"): continue @@ -741,9 +752,9 @@ class ManFormat(OutputFormat): if args.parameterdescs.get(parameter_name) =3D=3D KernelDoc.un= described: continue =20 - self.data +=3D f'.IP "{parameter}" 12' + "\n" + self.emit(f'.IP "{parameter}" 12' + "\n") self.output_highlight(args.parameterdescs.get(parameter_name)) =20 for section, text in args.sections.items(): - self.data +=3D f'.SH "{section}"' + "\n" + self.emit(f'.SH "{section}"' + "\n") self.output_highlight(text) --=20 2.49.0