From nobody Tue Oct 7 08:58:01 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 DEAD91FBEA2; Thu, 10 Jul 2025 23:31:53 +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=1752190315; cv=none; b=OIgytWAgLKLcQWU8gwUc0L4x5MBmHCIRaWEVv1ZjTJZqPGQHA3cd5CeJvvtG8EDJcYpGyKxaU7VASugIifAFXywoKi2S4Y8iLt9dBrdiJLkQnaQG2Jq+NWxvzSR4xK4Eyz9yc+jtxvnFOMS8uI7A48LfmkFqyBqvnjvf0POk3Qw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752190315; c=relaxed/simple; bh=Q1YUx91y5nYhB6VU82yWweGV/eOwFVOIzRSUEm0+ueg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=CglwmeARPF4g6goISVjow/6lE0QHQG5d+Ap5/58XScrv34RHYu7WJiJS51w3Owjw1vwpS4RVv634jQOBLbf/q36W84jFU6vNi5joAKcvw/lmtKfqrfp+fVyxkatgdQMofQLdVc3WEdc82a+RA/yWS8v6gFhWUtZhyt8n45WFOhY= 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=Hw0MpmB/; 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="Hw0MpmB/" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net E676440AB5 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1752190313; bh=VuniN21Y4B6Zp1MwsGk1HnxqjkJQcalXLlnY4fhQ904=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Hw0MpmB/GDbJLWi4oV3ClSutTbd6LnqynpkzcPYLUOTE5kGD1AAlHvI+jtOK/pCgQ To6ojT9hCC6WdZ7Ot684rrHMf7gPk3zGTOqnkokxpyZId+Yd5eAhBbN4oQN6O2QbY5 Y+Fvs91RdfLx7wTKgXOZLNHOw2L36UldVfzjr4yfxnydq7tbqnq5Py+7WDU7on5Nl3 kWMySkXC+KylFoHTeJJC6dHY4qvqmDB6TOk0VK2BdyUpgk/etzY639iXSJhycLWIEL J5q1/QQWr31FIPVKS01QZCAe/Oz/ngV40gTc+uveRYvJB4sueY639wBsZrmSKWczAT ZE+6GESuOiL0A== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id E676440AB5; Thu, 10 Jul 2025 23:31:52 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH v2 01/12] docs: kdoc; Add a rudimentary class to represent output items Date: Thu, 10 Jul 2025 17:31:31 -0600 Message-ID: <20250710233142.246524-2-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250710233142.246524-1-corbet@lwn.net> References: <20250710233142.246524-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- 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 Tue Oct 7 08:58:02 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 6A85C1FF1C4; Thu, 10 Jul 2025 23:31:54 +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=1752190315; cv=none; b=azY1EBITw5ENnbUcylVuZ1DP6vaOdLOoK3Gw5rdx3RnnUWBql+j4J8KG95b6q/HZJWyTxAf0Xxl/c5SBJEr5aUZheQ45G/NFHETjBPl6HvSoi7WaJa0lQQPFUtVy0Ta2z4MTtQW8x8KHDjQF5JgX2xvlnbjTbhr/HGcegt4dOGY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752190315; c=relaxed/simple; bh=SKv7WuVd34Kw+59dLBPWsq0YXFvKu18KsiExoJYXPeY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=hl7D9scxwM6tYec8MBpByTisTuz1Ki/xYlsVgnXcNcmx3k/OCtrIWruXVu8AzReE1CPk9dzNjBU1UUuHfTgcajqEO9Y5K7hiaJfAIXe3ibWl8+wn5+4rv12DUcB8G0ml0jdnrFuqoqT2bXrtk/oKjV1JGzjWDfGCMQ2Bq9cEa+U= 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=naJMHLFD; 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="naJMHLFD" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 7167540AD8 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1752190313; bh=XyiS4t2j2GRbyuM73we2cc8sYm2VrL8GXB9npdvoq8k=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=naJMHLFDr9O/pzTUo2Tw8NVGXjWwFMNHzs1coXfdlrRQREnvHFZqHEvlqm0CqoN7P R5JiAEqTzdQy3wzB3SzTlZ7LwnnYYcxV2wa9U5ba1GzmNiSGfgwUAtnNAMzNHBOcVB G0HsFSkG3mMBN71aBkhQmWJVGhCo5HxVdIrAMREy+x6WL9lsN6KdrcqOBU90W9AuBQ xGpuT3676nK4LTw0QWM03JI0Q4ENswVOFPo0CkMm4I6CmW7YmmlbzNF+0J/6r2rCit GfrtIlovpqoGkuQ+roUREqA2KOdAEdHG/oCCSn3B+ZB32L6X6BrPVaILPeDJUxVPcc 96PlyIJkBsbXw== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 7167540AD8; Thu, 10 Jul 2025 23:31:53 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH v2 02/12] docs: kdoc: simplify the output-item passing Date: Thu, 10 Jul 2025 17:31:32 -0600 Message-ID: <20250710233142.246524-3-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250710233142.246524-1-corbet@lwn.net> References: <20250710233142.246524-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Since our output items contain their name, we don't need to pass it separately. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- 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 Tue Oct 7 08:58:02 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 AC362216E1B; Thu, 10 Jul 2025 23:31:54 +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=1752190316; cv=none; b=BW7VChfnIFEZVEAvdG8nFgC0aIpu5YsOLuZGStrqZuCBU6naBlEELSWRX9hj/MMNplWXCjoKb3BaTgUmq3vjmegC73CTFKE+3g6D4d57xXco2oom4nGJSLMmrrPKu7nBujux4ofjwtN3hRIxEkZyP/J8YNsdC/G3OAlksZgenEw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752190316; c=relaxed/simple; bh=Pgb8LSDtxIzqmAipgaHHQZ057ikA2yl3SNNhfO18ASU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=eUKwq4EQk913taGhaegB8hynVUnU9bBXPHfMlRYEAF1uKM6hQuktHlbkFGmWwWlbscVGjOTS1zZdwWONFyQfTtjbnIU9pGJTaos16MvHPl9NlqqbBjdoXF83x2SBFvx0jQMfPyGKLhnHlOaiNgDDmdrzMQ7VWzfCshKEtR9X+tE= 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=dfC4xSJc; 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="dfC4xSJc" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net F073340ADC DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1752190314; bh=NYjm9zhDgUZ/tCYwlre9mvWRl7P3MGpd9SwqGGfx1rY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=dfC4xSJcm52hUCRnl0QrGJULHz55bDwUkPvlQF1OtLn/UfoXqurjGeye8kP+LOAs+ ulJHTszuEY7TBNCx6sgYx7eGEAoscu+f5b64uCif+BE09odcbOLdrfBRKg+cYBsjdR sUHlqS5LnjCUPrm+6n+Nl+l6/IHZv3D2Xr3YoTNmGY9yjEM3QYeqLKi2C5UwblHP2a PZv7UibqLXdx4iACVZjJB5RZ7FoHVp7MmHVYQDsbof4A8EljmbogeP+RVrj2frPgat z5OMaDM9WIb72WufK+ItkldvNqMoZ0Ovz21waWuHVMu/n4pbfZIM4dij8Ez3VY7N9G nNTgwskUzWoqw== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id F073340ADC; Thu, 10 Jul 2025 23:31:53 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH v2 03/12] docs: kdoc: drop "sectionlist" Date: Thu, 10 Jul 2025 17:31:33 -0600 Message-ID: <20250710233142.246524-4-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250710233142.246524-1-corbet@lwn.net> References: <20250710233142.246524-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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: Mauro Carvalho Chehab --- 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 Tue Oct 7 08:58:02 2025 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 76AAE2951D5; Thu, 10 Jul 2025 23:31:55 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752190317; cv=none; b=PfIeWQXeRXtboFKyr0yeiMqLeTAiGkxy+xDZslxIW7oCnuDyOvvMbE8uiGzT6ixlCREl9Q1IolRygZnkLya/5aRf+DFCjr6RasIx0ChsRLoGslqxENE8m3OmRzFl7GU9Bpr/k3LNpibc0i+P9Ic4k2BpUlzzf0BqvI24nyqGTek= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752190317; c=relaxed/simple; bh=qMYRnA9XGZ7/zWzvmU7F63GHBA2J7wD1/lg6b1EWtDI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Y2bG8zl1unox3drMJNLHfQ+howPGxIHpGQhiygzqXbJZJU5/ozXc7uKOSNffchlg0JSoJpIj30eyLvVaTDFNYTAp2mOHW6Y7Bw6omfQAlISR5HI+UlQz0OOiyYdjlpHdM6tJ0Tbk5m5xCSsGCmHD6ICK+cNSsb9wpNVLaiNbGkQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=ppuLxiWx; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="ppuLxiWx" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 7B1ED40ADE DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1752190314; bh=M/kKBUsmG0hdLVav5VykrUa9ChXBFaOvaMmLshR6FAk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ppuLxiWxsi3OTJSLdl+hq9aIG3oGw9gafZ3EmWzF3hDwNXiN6WfYj21+6Z06NQa84 0361ZnZCEXp8z1+cU19kcqy/dsyxvF/da8RehRHVi7coiVechnpPPxePzFnqUY4dUp mJeWxAsJ7OjA5xM6qsxLAFJVztdbSwOFgvAdRTg0qPz0aGhNkEkG398TtEJdKaZDi2 SbbrV7zn9TAxP3gPVgPPhV17ICnQR++HyQWk4Vkpbt/Ppa3Yr8SlyK3X/8Fg7ThbFL CLUi7yOHMGRrB8rW9rBcAchWazOBuCN9cxuLVFk3uV+fJ+TXoTFpb0qNIH2knrE2F5 MroCCQ7Q+p2KA== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 7B1ED40ADE; Thu, 10 Jul 2025 23:31:54 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH v2 04/12] docs: kdoc: Centralize handling of the item section list Date: Thu, 10 Jul 2025 17:31:34 -0600 Message-ID: <20250710233142.246524-5-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250710233142.246524-1-corbet@lwn.net> References: <20250710233142.246524-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" The section list always comes directly from the under-construction entry and is used uniformly. Formalize section handling in the KdocItem class, and have output_declaration() load the sections directly from the entry, eliminating a lot of duplicated, verbose parameters. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_item.py | 9 +++++++++ scripts/lib/kdoc/kdoc_output.py | 36 ++++++++++++--------------------- scripts/lib/kdoc/kdoc_parser.py | 20 +++--------------- 3 files changed, 25 insertions(+), 40 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_item.py b/scripts/lib/kdoc/kdoc_item.py index add2cc772fec..f0b2b9082c56 100644 --- a/scripts/lib/kdoc/kdoc_item.py +++ b/scripts/lib/kdoc/kdoc_item.py @@ -9,6 +9,8 @@ class KdocItem: self.name =3D name self.type =3D type self.declaration_start_line =3D start_line + self.sections =3D {} + self.sections_start_lines =3D {} # # Just save everything else into our own dict so that the output # side can grab it directly as before. As we move things into more @@ -24,3 +26,10 @@ class KdocItem: =20 def __getitem__(self, key): return self.get(key) + + # + # Tracking of section information. + # + def set_sections(self, sections, start_lines): + self.sections =3D sections + self.section_start_lines =3D start_lines diff --git a/scripts/lib/kdoc/kdoc_output.py b/scripts/lib/kdoc/kdoc_output= .py index 4895c80e4b81..15cb89f91987 100644 --- a/scripts/lib/kdoc/kdoc_output.py +++ b/scripts/lib/kdoc/kdoc_output.py @@ -338,11 +338,7 @@ class RestFormat(OutputFormat): starts by putting out the name of the doc section itself, but that tends to duplicate a header already in the template file. """ - - sections =3D args.get('sections', {}) - section_start_lines =3D args.get('section_start_lines', {}) - - for section in sections: + for section, text in args.sections.items(): # Skip sections that are in the nosymbol_table if section in self.nosymbol: continue @@ -354,8 +350,8 @@ class RestFormat(OutputFormat): else: self.data +=3D f'{self.lineprefix}**{section}**\n\n' =20 - self.print_lineno(section_start_lines.get(section, 0)) - self.output_highlight(sections[section]) + self.print_lineno(args.section_start_lines.get(section, 0)) + self.output_highlight(text) self.data +=3D "\n" self.data +=3D "\n" =20 @@ -635,23 +631,20 @@ class ManFormat(OutputFormat): self.data +=3D line + "\n" =20 def out_doc(self, fname, name, args): - sections =3D args.get('sections', {}) - if not self.check_doc(name, args): return =20 self.data +=3D f'.TH "{self.modulename}" 9 "{self.modulename}" "{s= elf.man_date}" "API Manual" LINUX' + "\n" =20 - for section in sections: + for section, text in args.sections.items(): self.data +=3D f'.SH "{section}"' + "\n" - self.output_highlight(sections.get(section)) + self.output_highlight(text) =20 def out_function(self, fname, name, args): """output function in man""" =20 parameterlist =3D args.get('parameterlist', []) parameterdescs =3D args.get('parameterdescs', {}) - sections =3D args.get('sections', {}) =20 self.data +=3D f'.TH "{args["function"]}" 9 "{args["function"]}" "= {self.man_date}" "Kernel Hacker\'s Manual" LINUX' + "\n" =20 @@ -692,15 +685,14 @@ class ManFormat(OutputFormat): self.data +=3D f'.IP "{parameter}" 12' + "\n" self.output_highlight(parameterdescs.get(parameter_name, "")) =20 - for section in sections: + for section, text in args.sections.items(): self.data +=3D f'.SH "{section.upper()}"' + "\n" - self.output_highlight(sections[section]) + self.output_highlight(text) =20 def out_enum(self, fname, name, args): =20 name =3D args.get('enum', '') parameterlist =3D args.get('parameterlist', []) - sections =3D args.get('sections', {}) =20 self.data +=3D f'.TH "{self.modulename}" 9 "enum {args["enum"]}" "= {self.man_date}" "API Manual" LINUX' + "\n" =20 @@ -727,24 +719,23 @@ class ManFormat(OutputFormat): self.data +=3D f'.IP "{parameter}" 12' + "\n" self.output_highlight(args['parameterdescs'].get(parameter_nam= e, "")) =20 - for section in sections: + for section, text in args.sections.items(): self.data +=3D f'.SH "{section}"' + "\n" - self.output_highlight(sections[section]) + self.output_highlight(text) =20 def out_typedef(self, fname, name, args): module =3D self.modulename typedef =3D args.get('typedef') purpose =3D args.get('purpose') - sections =3D args.get('sections', {}) =20 self.data +=3D f'.TH "{module}" 9 "{typedef}" "{self.man_date}" "A= PI Manual" LINUX' + "\n" =20 self.data +=3D ".SH NAME\n" self.data +=3D f"typedef {typedef} \\- {purpose}\n" =20 - for section in sections: + for section, text in args.sections.items(): self.data +=3D f'.SH "{section}"' + "\n" - self.output_highlight(sections.get(section)) + self.output_highlight(text) =20 def out_struct(self, fname, name, args): module =3D self.modulename @@ -753,7 +744,6 @@ class ManFormat(OutputFormat): purpose =3D args.get('purpose') definition =3D args.get('definition') parameterlist =3D args.get('parameterlist', []) - sections =3D args.get('sections', {}) parameterdescs =3D args.get('parameterdescs', {}) =20 self.data +=3D f'.TH "{module}" 9 "{struct_type} {struct_name}" "{= self.man_date}" "API Manual" LINUX' + "\n" @@ -782,6 +772,6 @@ class ManFormat(OutputFormat): self.data +=3D f'.IP "{parameter}" 12' + "\n" self.output_highlight(parameterdescs.get(parameter_name)) =20 - for section in sections: + for section, text in args.sections.items(): self.data +=3D f'.SH "{section}"' + "\n" - self.output_highlight(sections.get(section)) + self.output_highlight(text) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 2e00c8b3a5f2..608f3a1045dc 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -272,13 +272,13 @@ class KernelDoc: item =3D KdocItem(name, dtype, self.entry.declaration_start_line, = **args) item.warnings =3D self.entry.warnings =20 - sections =3D item.get('sections', {}) - # Drop empty sections # TODO: improve empty sections logic to emit warnings + sections =3D self.entry.sections for section in ["Description", "Return"]: if section in sections and not sections[section].rstrip(): del sections[section] + item.set_sections(sections, self.entry.section_start_lines) =20 self.entries.append(item) =20 @@ -824,8 +824,6 @@ class KernelDoc: parameterdescs=3Dself.entry.parameterdescs, parametertypes=3Dself.entry.parametertypes, parameterdesc_start_lines=3Dself.entry.par= ameterdesc_start_lines, - sections=3Dself.entry.sections, - section_start_lines=3Dself.entry.section_s= tart_lines, purpose=3Dself.entry.declaration_purpose) =20 def dump_enum(self, ln, proto): @@ -908,8 +906,6 @@ class KernelDoc: parameterlist=3Dself.entry.parameterlist, parameterdescs=3Dself.entry.parameterdescs, parameterdesc_start_lines=3Dself.entry.par= ameterdesc_start_lines, - sections=3Dself.entry.sections, - section_start_lines=3Dself.entry.section_s= tart_lines, purpose=3Dself.entry.declaration_purpose) =20 def dump_declaration(self, ln, prototype): @@ -1079,8 +1075,6 @@ class KernelDoc: parameterdescs=3Dself.entry.parameterd= escs, parametertypes=3Dself.entry.parametert= ypes, parameterdesc_start_lines=3Dself.entry= .parameterdesc_start_lines, - sections=3Dself.entry.sections, - section_start_lines=3Dself.entry.secti= on_start_lines, purpose=3Dself.entry.declaration_purpo= se, func_macro=3Dfunc_macro) else: @@ -1092,8 +1086,6 @@ class KernelDoc: parameterdescs=3Dself.entry.parameterd= escs, parametertypes=3Dself.entry.parametert= ypes, parameterdesc_start_lines=3Dself.entry= .parameterdesc_start_lines, - sections=3Dself.entry.sections, - section_start_lines=3Dself.entry.secti= on_start_lines, purpose=3Dself.entry.declaration_purpo= se, func_macro=3Dfunc_macro) =20 @@ -1137,8 +1129,6 @@ class KernelDoc: parameterdescs=3Dself.entry.parameterd= escs, parametertypes=3Dself.entry.parametert= ypes, parameterdesc_start_lines=3Dself.entry= .parameterdesc_start_lines, - sections=3Dself.entry.sections, - section_start_lines=3Dself.entry.secti= on_start_lines, purpose=3Dself.entry.declaration_purpo= se) return =20 @@ -1159,8 +1149,6 @@ class KernelDoc: =20 self.output_declaration('typedef', declaration_name, typedef=3Ddeclaration_name, - sections=3Dself.entry.sections, - section_start_lines=3Dself.entry.secti= on_start_lines, purpose=3Dself.entry.declaration_purpo= se) return =20 @@ -1642,9 +1630,7 @@ class KernelDoc: =20 if doc_end.search(line): self.dump_section() - self.output_declaration("doc", self.entry.identifier, - sections=3Dself.entry.sections, - section_start_lines=3Dself.entry.secti= on_start_lines) + self.output_declaration("doc", self.entry.identifier) self.reset_state(ln) =20 elif doc_content.search(line): --=20 2.49.0 From nobody Tue Oct 7 08:58:02 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 DDB762D1F6B; Thu, 10 Jul 2025 23:31:55 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752190317; cv=none; b=OcWS7lJknzrV/JoXHWpIMXLNbEve+qnvvzZWxNjO40JXh3/aN8t7LS5v/3GPn9QGPNL1iURKQx7j84vHGVaCskZq1CsJFPQwX1z34uHbJZBHsah80Kg7DpaWiatVvV+OKZyf6QYwbHxwbW8Nil1ZJSLc/xrnSLhuFxSOmRkae8M= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752190317; c=relaxed/simple; bh=P6yhrqkUMPctdFr2ViV3gZT6hN06lIi0XE/BpYCeQE8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=VSXkPW+RBoyOXAmvmmfsDXLIk/YLUdiGN7RlrhP2tnQUow6KLxCa6pO3wrYrKVOQ/n8CkWva+Vbgp77+Bi4v6DAjXgVO0Z1zSyLpN4TFO7PAyQ2JAJaaIbch0oG1I3CB9E0OWcczzvBotNR9dxESeAHQtT97MLkKMqmTjHXybY0= 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=lE+5/rsi; 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="lE+5/rsi" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 07D94406FA DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1752190315; bh=AqFbr2+PxoELXgCLPo6n2CUdGey5ExLjhnXgIypFlxA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=lE+5/rsiSlpLqVlyd0ZzDwBobPtZxxZQ9SDR6jMkE5v7ugfO+9B/ia98dRLQ6URrA tsoEEaRm6m85tT2A/4fYS6bUVGHdL7toUoCB9S5f1A6Dj8ef3kk0Si1CpAquQVTEa+ mK4bt1fWedqjoUwiD0bJemn0bzAfGWNqrRn0JD/6RnX/ebVqlHFM9JawjmVffUaOja OYU0HS8GmemxImReqBYWh3Hk5veCRp+yXtZ5giC7YGOznBtCc1ODobSUSrIPmzsE86 yqo2PWUWNWuUZqtTr7mXfnU+GFYxv+fTBa8yoqyVyTenCNOPeT43fve/UT7QgreLxc IbDCVlhXF6p9Q== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 07D94406FA; Thu, 10 Jul 2025 23:31:54 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH v2 05/12] docs: kdoc: remove the "struct_actual" machinery Date: Thu, 10 Jul 2025 17:31:35 -0600 Message-ID: <20250710233142.246524-6-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250710233142.246524-1-corbet@lwn.net> References: <20250710233142.246524-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" The 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. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- 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 Tue Oct 7 08:58:02 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 5BE462E6135; Thu, 10 Jul 2025 23:31:56 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752190317; cv=none; b=b7aglSHf0BqlAwoVYpCwcZNNZDsoW+d7f7q+ObntYOhIX4VRceOYVEBVyPDejsY8V0nefButsu+8H0/9a8sXd6bkbzi6/AKFut8JJ2M0XgpSO+2cFJT6wcT379dgvqq7Mpl4URAcoMhVKAct1bIp7XRL7p2vlJKWwRTtNxbZeh0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752190317; c=relaxed/simple; bh=CEmS+NvjxQazKvv4Mw4nPnbu5aQTJLiBK7thQk03xT8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=nWMo+UBNLp+nH9L7k3EuVYO/kI4vZg4+G2I+WRjoBvAPCzzKm7CBI0W6hxEz21Eg0jvnlj2ASSz87Xlwutc1ExZv60FP5KuOK35BflWu3KRz709gDyV1WeVyyZl6ir8PziH3Aq2goaoVWg3O2PS/L8GdqES9C2c4Nz4Zm2HNrno= 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=KzoIrpeb; 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="KzoIrpeb" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 87BA440AB5 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1752190315; bh=gJHOkXvIy/8jemb/jqaH5LGkDKd+1dRGQTpjc5JSSAE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=KzoIrpebGgZl2QLNpShvFrJYvjEAS4R816JrXXK7eWlKRSxEmdVpAukxZok5fGnXU AscqaAoY8PVEY8vS6ZL++Q30JyGfz75jeSlGtknMAFz+Q+67DCpqgz6CzY9d178Om/ eqM/XlyB7+tqIe0TDGyy9MeC5H3PKIDus5oyLiKlbeFB01Pj8Ajq5UbysIg6KJJxpe 6h5rqc/1Q4/L3S3zg9lj1JlWntHJL0ytqErhouyXpK/oB0QexYcXHJ70UQ2vFoHIxB +nhZ7cNNPoLIyHNtJaX5mQHXYvRhQ7PoW3bqbP2BBTZ7RAGqruQF/K9bCnlI6cIQFH o781Jgi092beQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 87BA440AB5; Thu, 10 Jul 2025 23:31:55 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH v2 06/12] docs: kdoc: use self.entry.parameterlist directly in check_sections() Date: Thu, 10 Jul 2025 17:31:36 -0600 Message-ID: <20250710233142.246524-7-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250710233142.246524-1-corbet@lwn.net> References: <20250710233142.246524-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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(). Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- 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 Tue Oct 7 08:58:02 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 BDA31306DD2; Thu, 10 Jul 2025 23:31:56 +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=1752190318; cv=none; b=gxYP1Iqyq1ckuGjKXvyGpV692Prpr8Gmrv1XFcFoAk3jO1oD/+/MmtBpm4bQyCathumnMZcrXhC2II3AgNKrV2z2m2ABq6KgIVLUVhtupCCXD+ZB1LrPCUJkQLGB0s5A2ks7DFi+aYcSBn+9Yti4Csh3ojdA/PMRfC2DR+CG0xQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752190318; c=relaxed/simple; bh=yi3E5gGZtFWAfnqaMvkeYMGQdRCxjIcRoAvpERtedZs=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=sG4yFMYPlKuQOXI/V4rubaPhgeUuoEDZZ/KM4Ws1fW9Ge5PstAl7v+ovvDu3qkrjZLZZqDPLi1SpP6g4oD0SD3Zlkgtjq0c86uL/qnDii0RXfaDGVO0zwV442WOfRZA0NyAhkydXJl65a5kYUOqSGN3uCl7giEiNgCqFbfpyE1U= 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=crjqaG/p; 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="crjqaG/p" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 138D140AD8 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1752190316; bh=mVkW5pQctwOVUnvld2bEO+nCywghD/K9nqJLvCYfBNc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=crjqaG/pb+ZCBs2GF2ee1eodmKlu6vhSHtvuA8q7M0kMhWfSxQMgAqT46QPw7+HUG kg8TlS3Wf2aNz9xwZXbtkrkY9AuWxhQFaIDH4JjRvgPbid5wCGx0IwaonvyzcxMiuu CTkOjYhaK7fU85Hb8m6Q4A6/SaOxFQyFoPaqM/rU0yrFsL/0BM9SyhFYv6BQ0hvroO D1FHuQi5/a0NdrcJ3zPyPw2NPkGfQdm+PZF8sf2O+DkFdRv8C1hbW44/vEBfi/FOyo /xFRfQmtYCaCjuqUbLURRLG5hGaoKTk3w551ViXRd/Vlf4EUZgeqgNaRK3V6BA67MN 5WBC41Sb4b3Ww== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 138D140AD8; Thu, 10 Jul 2025 23:31:56 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH v2 07/12] docs: kdoc: Coalesce parameter-list handling Date: Thu, 10 Jul 2025 17:31:37 -0600 Message-ID: <20250710233142.246524-8-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250710233142.246524-1-corbet@lwn.net> References: <20250710233142.246524-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_item.py | 11 ++++- scripts/lib/kdoc/kdoc_output.py | 75 +++++++++++++-------------------- scripts/lib/kdoc/kdoc_parser.py | 23 ++-------- 3 files changed, 42 insertions(+), 67 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_item.py b/scripts/lib/kdoc/kdoc_item.py index f0b2b9082c56..beac5c70a881 100644 --- a/scripts/lib/kdoc/kdoc_item.py +++ b/scripts/lib/kdoc/kdoc_item.py @@ -11,6 +11,9 @@ class KdocItem: 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 @@ -28,8 +31,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 Tue Oct 7 08:58:02 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 440E9307490; Thu, 10 Jul 2025 23:31:57 +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=1752190319; cv=none; b=KQ6ev5p8UrvRHkeZYT2bENet22sDMf4wKwBCROo056w8YaXxcE4tr+f3uQP7RZT5cyWovV/xjrR6aCqXQKCvUf5KQcucv1/6jnN/biDy6QaZCOtW5C19/krvtsDUHlrTDj3PaI/0M36eOh5vXNA6rlbMu/zxY1VVyJmfyqbPQck= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752190319; c=relaxed/simple; bh=dOjiYIKVE+nBbTt++hi20OX2BvwRD4RK+k8MXg3fhBE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=kg174KZqF/YIPShI19d9lgdwiqH0AIxRX0equ6Af70NsTaR9xO4HNRvERjZsyqZR52ejB8pbuYlHpb0dc3YJ695PRdRvXagUTDY8UbYntXQANoRqNqu7uNZUmT32/hhanL2C4MqLKAzA45pn55r6qIH99WC+F7HxHODRIAVw2gA= 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=sCe+dJh+; 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="sCe+dJh+" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 9368C40ADC DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1752190316; bh=qisX9BmJTXk4+PR/gFbDRpQ4AeQji/c4gWlkfrjsDK0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=sCe+dJh+WXeTxtCu9TyJVJIV9M7jPESXV2k+m4tsswt533NKgNt0zwW3vOQgT3yHc MoUrebJvwah6W4S0xFeybI4WjEJwlhT6sIWAZeQ9AIaq4kAPX2c2V51s+6+N5/FS9X G0qKjldGQC2lEFEJssJg4kFez9VmrM9PhNsQzaMMsDebmuGi4Ozhh4Gzdd6Pzy5T3b jM9eYv4WvB1eWxgFSKkf+vZ6DtTppZvjoU4Guzg54737M9PA9as3O6wsp9u/ElsKAO DJx1IJulbXSLotErJwTBpPoON5TtZO90NUd7R6n0UNlOaX/G+kg+EPB7LTM6LK2gJU je8wTOGCW+8Vg== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 9368C40ADC; Thu, 10 Jul 2025 23:31:56 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH v2 08/12] docs: kdoc: Regularize the use of the declaration name Date: Thu, 10 Jul 2025 17:31:38 -0600 Message-ID: <20250710233142.246524-9-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250710233142.246524-1-corbet@lwn.net> References: <20250710233142.246524-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- 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 Tue Oct 7 08:58:02 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 11CEF307AD8; Thu, 10 Jul 2025 23:31:57 +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=1752190319; cv=none; b=abs4fAePfofRCJZU/EEwa0OzCdxiz5yw4b1YAibd2ihy9jqtz2XTk2gu66x0F1mS5J/gmqr96KJUu+Vt/26/o9HiXtam8jE3DGKl+VbWic/6ZmreElcCXxf1A/d8+3bMTM06n1GHfP2oXRIUZnaYRjm8rAhv3bAH47iG721VPus= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752190319; c=relaxed/simple; bh=tbOvNdFwAz7DluAs34x2f5JXEIHvMZMO8z4scT0/uo8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=jwmjwb6oIemaISKx/1JJmoFGNwpB4tiK9cjwLpL8Avtqb01jTJa30dJ2lp1D+qatCo873vjQ0ILXFuAh4TKOCuDtAuecomW66vAXSRv1Q9W0gry1y2MQPxtq/L31y0cNjcoxkdD7Fz506zvhPqlDwnjAIkJfxGButLvVwqZObQI= 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=sIvIcwYa; 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="sIvIcwYa" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 2151840ADF DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1752190317; bh=lmv2UYWelgqU/j6Ln6KNIN6Kr5IxIFH4NLkcLWXjSok=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=sIvIcwYao7Imeozm411KCWZU3FKPNJdDjwX9UClTDdPL6rA0a3QCqaf3iiC66DWtZ zkecHwmgclVn0kufbQHM0w8vfBUsL7jzWk49UqM38pGaWiLh48XOsRKedSPSbXbSCq u+2WpYv4b2GfPf2rj5G4xe+I2tXTkqS/mLzFxXQlUqCjqlijVwZZ5j/r/8raXJ+gRe nWqKyrp7c/LHSF8NuMYR8ZUqm3uitT695x+7Oi0JvwQwbxA8TlU0lfDCUsuDIYUJrE jaOEg1PyWLNXkCnr8pZX1Mzih0ziFcR8LLPE/YeiJzLVlcyL1mAoLs4mC/nd4R3gWZ YiUZuXsUrGJQQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 2151840ADF; Thu, 10 Jul 2025 23:31:57 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH v2 09/12] docs: kdoc: straighten up dump_declaration() Date: Thu, 10 Jul 2025 17:31:39 -0600 Message-ID: <20250710233142.246524-10-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250710233142.246524-1-corbet@lwn.net> References: <20250710233142.246524-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Get rid of the excess "return" statements in dump_declaration(), along with a line of never-executed dead code. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- 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 Tue Oct 7 08:58:02 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 58DC5307AF3; Thu, 10 Jul 2025 23:31:58 +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=1752190320; cv=none; b=G/Lppm7k61mRpkjrFgptBB/WYuDEGNjhxR26WGbiABsq8lLmPeUocH6VFDbYcrnygFEOdUuwxgdAynU313eowi+nqBR/QnuDklfGaywCTs1kGOUMp9Oh2xhuCknp3UBeR/v/ve+/ID5mU/gy3uSMhQPT594/KljeDWJm3OpgKMc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752190320; c=relaxed/simple; bh=4nh3cywrUze4Xrhhvl/aFhvIptVuid/szc3DGTHSGoU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=tjLp4d+xXK7iZpMwNqFvS7NR/sZQqz6JND4c9yim6kvVJ1kHyoguZKaFS67Adv+62x0LYlGhAcTKuwlND1QxK1XSX9jmjw6jlAmwY8RDxBq6P2xO5iJ9qpQ0YwUMy5aYGJgSJP0UX04rC0F3nIFYax3+H/SymNAmvbzd6Ds2Gzk= 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=G+AiduJS; 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="G+AiduJS" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net AAE23406FA DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1752190318; bh=S11g0dvo4Gp8wnfQWL7KxGwp6Pr2KHF/P4OTfx/g+II=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=G+AiduJS6AtUNPDom5xHtTNrQg/0u/ALUtTsW4uJSO+WpikX85DA8pw0FlDVWOQe8 tls++VTlNPKBa2KxA/Z7HZtQRLmY9q4AoFgGoW/3k5wvtdxSsum46ORdoqic/Mg9Mp HulINH1QfhxuSR02vu+xEpY4DZs+PdOx3HgwaCUkVzXJWri8j0rDkM2UDGZ6k9tCPl 8Di2gfDovWnUWAxNf0uJKjyGvOkR+KV3EmwvOsFuetO7vMiHjJKYW9JPhE38cPl38j xmMC6Ip6DclkvOH12UkL68IHMjd1qzReoEX72NhEz9/qnavKL8+neT2vy3aeXNqgL3 378QLwrEbpaKQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id AAE23406FA; Thu, 10 Jul 2025 23:31:57 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH v2 10/12] docs: kdoc: directly access the always-there KdocItem fields Date: Thu, 10 Jul 2025 17:31:40 -0600 Message-ID: <20250710233142.246524-11-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250710233142.246524-1-corbet@lwn.net> References: <20250710233142.246524-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" They are part of the interface, so use them directly. This allows the removal of the transitional __dict__ hack in KdocItem. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- 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 beac5c70a881..fe52d87fda88 100644 --- a/scripts/lib/kdoc/kdoc_item.py +++ b/scripts/lib/kdoc/kdoc_item.py @@ -22,10 +22,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 Tue Oct 7 08:58:02 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 E0BE13093BC; Thu, 10 Jul 2025 23:31:58 +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=1752190320; cv=none; b=UtDeePYCgPMNrSShGt/kkVJ9y2VdATy/jcdkzmXK6p22JOV9QbUAy5vNVYw70C69EliP7iq2B3T6/xdZlu/iDOekPnGeCUye8420FiUuuB1GxTGwH2198Tr8LmvNAwvqLo5ztCZqTyaPrBAKquHoIpxs1gZSTi2JsmpI1I34Pjc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752190320; c=relaxed/simple; bh=dECE7HmGYRkH+wFN9HM0uf4VtBgfKt5FWt2EPDfKnrU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=TO06lNnAjKt9uNTHL6j7FdyBKDQUmjnWTGogs/W9nSZ/oGevLjH5O+5NENWQJf5+JEE10Uh4JtyRuywFbyhwsW9yKx/Rnv9LL4W21GhSPv6vqjlFHq4ZkXhnBGWjBVYkAOAlOSpBus+UGpZP1E9F+MhKLv3mfycEv/WbjXqmi6I= 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=jHj5Q8u1; 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="jHj5Q8u1" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 38BD540AB5 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1752190318; bh=nPOfJuokmVPpEF/4Hc1zpZaBuvlA3dKu+HWEiyN98XE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=jHj5Q8u1vBkg9Zkb2jHuyUCURSzP5asEjJi4ROq0PLwmRJvM6PF5mggcJt8R+zF/t FXC6X9gyypTr5pUEQTot32ryGefynXaeQYGJ/Y6u5DQr0N4cJCEIKsdkTz7/7PkLmy W3a5uIGSPdd0s2CtTUGat+CdZCwelBXdnxxlKkiCbYrLSOT7wbVcebk88pYUF9NEPt 5z2uP1+CnlmrP8AmX0VNSm07x0fZD8j7x8cD0ZBtXkV8TRmTDaw8ufT0jmmv8hgauX zrtJ7OnIAQBcx5D5HSh49mEPpa0QpDsryiQVIUbjhBcmhdPFTIY7cTwiH36O7nNI9O We0FAKmXwLaJg== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 38BD540AB5; Thu, 10 Jul 2025 23:31:58 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH v2 11/12] docs: kdoc: clean up check_sections() Date: Thu, 10 Jul 2025 17:31:41 -0600 Message-ID: <20250710233142.246524-12-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250710233142.246524-1-corbet@lwn.net> References: <20250710233142.246524-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- 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 Tue Oct 7 08:58:02 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 9EC3F309A52; Thu, 10 Jul 2025 23:31: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=1752190321; cv=none; b=FIPso+jcvTjB0QxcNICnk5uLD2lDceJ21jXpQIdvvxRQx2Zm5iif5XwbkfHAkOB9fVKfzIL2L0jhU4GYMNnZNW9OvAd6jZ1xqkO1GEASDm4VGW7yDOyTAOd5eQat7vCrEkkXGWTzY/59tl+NAtjZ506/AQlEANEJXrQAKa8CQGY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752190321; c=relaxed/simple; bh=AYb/kMhuMfcuVGw0rn9Jk1tH146m3ywJMggP+HSSk9Y=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=YrB4aqVAGLkxt+TMhYlUm/YRu3AzXDe9wXBo+hjIbgfe9Ngh0s7bBK0HdKYtkRXfXbaFkc1SbOAjjaCKWvq2y9nxAbRiEvJk4e7h3Q8VKz1fmTXMMsVe+xayZgdPE9HdjETGNn8MCVMHdJiKpBAApdQq8XB2rq4VTpaEwWHN2ag= 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=tNX+qUP3; 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="tNX+qUP3" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net B88FD40AD8 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1752190319; bh=osk9iDvYkT2VDAGfp2kEG6eJBgGqe8CmQwDNIjc52AU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=tNX+qUP31g1pp2x3jBWH+QbcKAbnRLxSbbBwHIg5ltZP0cQziXve9hkZp5ROi3URY 7NGCfxu8D6+2XluOxs66EDY8DNfFQAP8IBBvR/K/J3r/29Apk4rfaW/o+6rLL4TsEA 5v9HF53KZwwDGES02qb97u2rLfnZ41esNPIlJccvkYSmGNfMo0+my3qhBNyVHEP/oy e0381LiEk9T8EwiOjFXe/jeYkttkSiiTdySd6NWZOqyv+nw8xONgijsXyBDy0vHhfh lxL9sjkS0yYUxlnCoX2fe+w53Un13HGuRFbkGLD9+rXmbalCU/vUo67O4C7N3GsqEe Q6f6XgICENUNw== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id B88FD40AD8; Thu, 10 Jul 2025 23:31:58 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH v2 12/12] docs: kdoc: emit a warning for ancient versions of Python Date: Thu, 10 Jul 2025 17:31:42 -0600 Message-ID: <20250710233142.246524-13-corbet@lwn.net> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250710233142.246524-1-corbet@lwn.net> References: <20250710233142.246524-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Versions of Python prior to 3.7 do not guarantee to remember the insertion order of dicts; since kernel-doc depends on that guarantee, running with such older versions could result in output with reordered sections. Python 3.9 is the minimum for the kernel as a whole, so this should not be a problem, but put in a warning just in case somebody tries to use something older. Suggested-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index fdde14b045fe..23ac4ad204f4 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -12,6 +12,7 @@ Read a C language source or header FILE and extract embed= ded documentation comments """ =20 +import sys import re from pprint import pformat =20 @@ -238,6 +239,14 @@ class KernelDoc: # Place all potential outputs into an array self.entries =3D [] =20 + # + # We need Python 3.7 for its "dicts remember the insertion + # order" guarantee + # + if sys.version_info.major =3D=3D 3 and sys.version_info.minor < 7: + self.emit_message(0, + 'Python 3.7 or later is required for correct= results') + def emit_msg(self, ln, msg, warning=3DTrue): """Emit a message""" =20 --=20 2.49.0