From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
Akira Yokosawa <akiyks@gmail.com>
Subject: Re: [PATCH v2 03/12] docs: kdoc: drop "sectionlist"
Date: Fri, 11 Jul 2025 07:50:26 +0200 [thread overview]
Message-ID: <20250711075026.6da00103@foz.lan> (raw)
In-Reply-To: <20250710233142.246524-4-corbet@lwn.net>
Em Thu, 10 Jul 2025 17:31:33 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> 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 <corbet@lwn.net>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
> 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.
> """
>
> - sectionlist = args.get('sectionlist', [])
> sections = args.get('sections', {})
> section_start_lines = args.get('section_start_lines', {})
>
> - 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 += line + "\n"
>
> def out_doc(self, fname, name, args):
> - sectionlist = args.get('sectionlist', [])
> sections = args.get('sections', {})
>
> if not self.check_doc(name, args):
> @@ -644,7 +642,7 @@ class ManFormat(OutputFormat):
>
> self.data += f'.TH "{self.modulename}" 9 "{self.modulename}" "{self.man_date}" "API Manual" LINUX' + "\n"
>
> - for section in sectionlist:
> + for section in sections:
> self.data += f'.SH "{section}"' + "\n"
> self.output_highlight(sections.get(section))
>
> @@ -653,7 +651,6 @@ class ManFormat(OutputFormat):
>
> parameterlist = args.get('parameterlist', [])
> parameterdescs = args.get('parameterdescs', {})
> - sectionlist = args.get('sectionlist', [])
> sections = args.get('sections', {})
>
> self.data += 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 += f'.IP "{parameter}" 12' + "\n"
> self.output_highlight(parameterdescs.get(parameter_name, ""))
>
> - for section in sectionlist:
> + for section in sections:
> self.data += f'.SH "{section.upper()}"' + "\n"
> self.output_highlight(sections[section])
>
> @@ -703,7 +700,6 @@ class ManFormat(OutputFormat):
>
> name = args.get('enum', '')
> parameterlist = args.get('parameterlist', [])
> - sectionlist = args.get('sectionlist', [])
> sections = args.get('sections', {})
>
> self.data += f'.TH "{self.modulename}" 9 "enum {args["enum"]}" "{self.man_date}" "API Manual" LINUX' + "\n"
> @@ -731,7 +727,7 @@ class ManFormat(OutputFormat):
> self.data += f'.IP "{parameter}" 12' + "\n"
> self.output_highlight(args['parameterdescs'].get(parameter_name, ""))
>
> - for section in sectionlist:
> + for section in sections:
> self.data += f'.SH "{section}"' + "\n"
> self.output_highlight(sections[section])
>
> @@ -739,7 +735,6 @@ class ManFormat(OutputFormat):
> module = self.modulename
> typedef = args.get('typedef')
> purpose = args.get('purpose')
> - sectionlist = args.get('sectionlist', [])
> sections = args.get('sections', {})
>
> self.data += f'.TH "{module}" 9 "{typedef}" "{self.man_date}" "API Manual" LINUX' + "\n"
> @@ -747,7 +742,7 @@ class ManFormat(OutputFormat):
> self.data += ".SH NAME\n"
> self.data += f"typedef {typedef} \\- {purpose}\n"
>
> - for section in sectionlist:
> + for section in sections:
> self.data += f'.SH "{section}"' + "\n"
> self.output_highlight(sections.get(section))
>
> @@ -757,7 +752,6 @@ class ManFormat(OutputFormat):
> struct_name = args.get('struct')
> purpose = args.get('purpose')
> definition = args.get('definition')
> - sectionlist = args.get('sectionlist', [])
> parameterlist = args.get('parameterlist', [])
> sections = args.get('sections', {})
> parameterdescs = args.get('parameterdescs', {})
> @@ -788,6 +782,6 @@ class ManFormat(OutputFormat):
> self.data += f'.IP "{parameter}" 12' + "\n"
> self.output_highlight(parameterdescs.get(parameter_name))
>
> - for section in sectionlist:
> + for section in sections:
> self.data += 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 = {}
>
> self.section_start_lines = {}
> - self.sectionlist = []
> self.sections = {}
>
> self.anon_struct_union = False
> @@ -202,7 +201,6 @@ class KernelEntry:
> self.sections[name] += '\n' + contents
> else:
> self.sections[name] = contents
> - self.sectionlist.append(name)
> self.section_start_lines[name] = self.new_start_line
> self.new_start_line = 0
>
> @@ -275,14 +273,12 @@ class KernelDoc:
> item.warnings = self.entry.warnings
>
> sections = item.get('sections', {})
> - sectionlist = item.get('sectionlist', [])
>
> # 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)
>
> self.entries.append(item)
>
> @@ -828,7 +824,6 @@ class KernelDoc:
> parameterdescs=self.entry.parameterdescs,
> parametertypes=self.entry.parametertypes,
> parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
> - sectionlist=self.entry.sectionlist,
> sections=self.entry.sections,
> section_start_lines=self.entry.section_start_lines,
> purpose=self.entry.declaration_purpose)
> @@ -913,7 +908,6 @@ class KernelDoc:
> parameterlist=self.entry.parameterlist,
> parameterdescs=self.entry.parameterdescs,
> parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
> - sectionlist=self.entry.sectionlist,
> sections=self.entry.sections,
> section_start_lines=self.entry.section_start_lines,
> purpose=self.entry.declaration_purpose)
> @@ -1085,7 +1079,6 @@ class KernelDoc:
> parameterdescs=self.entry.parameterdescs,
> parametertypes=self.entry.parametertypes,
> parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
> - sectionlist=self.entry.sectionlist,
> sections=self.entry.sections,
> section_start_lines=self.entry.section_start_lines,
> purpose=self.entry.declaration_purpose,
> @@ -1099,7 +1092,6 @@ class KernelDoc:
> parameterdescs=self.entry.parameterdescs,
> parametertypes=self.entry.parametertypes,
> parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
> - sectionlist=self.entry.sectionlist,
> sections=self.entry.sections,
> section_start_lines=self.entry.section_start_lines,
> purpose=self.entry.declaration_purpose,
> @@ -1145,7 +1137,6 @@ class KernelDoc:
> parameterdescs=self.entry.parameterdescs,
> parametertypes=self.entry.parametertypes,
> parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
> - sectionlist=self.entry.sectionlist,
> sections=self.entry.sections,
> section_start_lines=self.entry.section_start_lines,
> purpose=self.entry.declaration_purpose)
> @@ -1168,7 +1159,6 @@ class KernelDoc:
>
> self.output_declaration('typedef', declaration_name,
> typedef=declaration_name,
> - sectionlist=self.entry.sectionlist,
> sections=self.entry.sections,
> section_start_lines=self.entry.section_start_lines,
> purpose=self.entry.declaration_purpose)
> @@ -1653,7 +1643,6 @@ class KernelDoc:
> if doc_end.search(line):
> self.dump_section()
> self.output_declaration("doc", self.entry.identifier,
> - sectionlist=self.entry.sectionlist,
> sections=self.entry.sections,
> section_start_lines=self.entry.section_start_lines)
> self.reset_state(ln)
Thanks,
Mauro
next prev parent reply other threads:[~2025-07-11 5:50 UTC|newest]
Thread overview: 21+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-07-10 23:31 [PATCH v2 00/12] Thrash up the parser/output interface Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 01/12] docs: kdoc; Add a rudimentary class to represent output items Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 02/12] docs: kdoc: simplify the output-item passing Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 03/12] docs: kdoc: drop "sectionlist" Jonathan Corbet
2025-07-11 5:50 ` Mauro Carvalho Chehab [this message]
2025-07-10 23:31 ` [PATCH v2 04/12] docs: kdoc: Centralize handling of the item section list Jonathan Corbet
2025-07-11 5:52 ` Mauro Carvalho Chehab
2025-07-10 23:31 ` [PATCH v2 05/12] docs: kdoc: remove the "struct_actual" machinery Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 06/12] docs: kdoc: use self.entry.parameterlist directly in check_sections() Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 07/12] docs: kdoc: Coalesce parameter-list handling Jonathan Corbet
2025-07-11 5:54 ` Mauro Carvalho Chehab
2025-07-11 12:45 ` Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 08/12] docs: kdoc: Regularize the use of the declaration name Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 09/12] docs: kdoc: straighten up dump_declaration() Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 10/12] docs: kdoc: directly access the always-there KdocItem fields Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 11/12] docs: kdoc: clean up check_sections() Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 12/12] docs: kdoc: emit a warning for ancient versions of Python Jonathan Corbet
2025-07-11 5:49 ` Mauro Carvalho Chehab
2025-07-11 4:29 ` [PATCH v2 00/12] Thrash up the parser/output interface Akira Yokosawa
2025-07-11 7:29 ` Mauro Carvalho Chehab
2025-07-11 13:17 ` Jonathan Corbet
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20250711075026.6da00103@foz.lan \
--to=mchehab+huawei@kernel.org \
--cc=akiyks@gmail.com \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).