* [PATCH v2 01/12] docs: kdoc; Add a rudimentary class to represent output items
2025-07-10 23:31 [PATCH v2 00/12] Thrash up the parser/output interface Jonathan Corbet
@ 2025-07-10 23:31 ` Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 02/12] docs: kdoc: simplify the output-item passing Jonathan Corbet
` (11 subsequent siblings)
12 siblings, 0 replies; 21+ messages in thread
From: Jonathan Corbet @ 2025-07-10 23:31 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa,
Jonathan Corbet
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 <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
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 = name
+ self.type = type
+ self.declaration_start_line = 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 = other_stuff
+
+ def get(self, key, default = None):
+ ret = self.other_stuff.get(key, default)
+ if ret == 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
from kdoc_re import NestedMatch, KernRe
-
+from kdoc_item import KdocItem
#
# 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
"""
- # The implementation here is different than the original kernel-doc:
- # instead of checking for output filters or actually output anything,
- # 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"] = self.entry.declaration_start_line
- args["type"] = dtype
- args["warnings"] = self.entry.warnings
-
- # TODO: use colletions.OrderedDict to remove sectionlist
+ item = KdocItem(name, dtype, self.entry.declaration_start_line, **args)
+ item.warnings = self.entry.warnings
- sections = args.get('sections', {})
- sectionlist = args.get('sectionlist', [])
+ 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:
- 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)
- self.entries.append((name, args))
+ self.entries.append((name, item))
self.config.log.debug("Output: %s:%s = %s", dtype, name, pformat(args))
--
2.49.0
^ permalink raw reply related [flat|nested] 21+ messages in thread* [PATCH v2 02/12] docs: kdoc: simplify the output-item passing
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 ` Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 03/12] docs: kdoc: drop "sectionlist" Jonathan Corbet
` (10 subsequent siblings)
12 siblings, 0 replies; 21+ messages in thread
From: Jonathan Corbet @ 2025-07-10 23:31 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa,
Jonathan Corbet
Since our output items contain their name, we don't need to pass it
separately.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
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
- for name, arg in self.results[fname]:
- m = self.out_msg(fname, name, arg)
+ for arg in self.results[fname]:
+ m = self.out_msg(fname, arg.name, arg)
if m is None:
ln = 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)
- self.entries.append((name, item))
+ self.entries.append(item)
self.config.log.debug("Output: %s:%s = %s", dtype, name, pformat(args))
--
2.49.0
^ permalink raw reply related [flat|nested] 21+ messages in thread* [PATCH v2 03/12] docs: kdoc: drop "sectionlist"
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 ` Jonathan Corbet
2025-07-11 5:50 ` Mauro Carvalho Chehab
2025-07-10 23:31 ` [PATCH v2 04/12] docs: kdoc: Centralize handling of the item section list Jonathan Corbet
` (9 subsequent siblings)
12 siblings, 1 reply; 21+ messages in thread
From: Jonathan Corbet @ 2025-07-10 23:31 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa,
Jonathan Corbet
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>
---
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)
--
2.49.0
^ permalink raw reply related [flat|nested] 21+ messages in thread* Re: [PATCH v2 03/12] docs: kdoc: drop "sectionlist"
2025-07-10 23:31 ` [PATCH v2 03/12] docs: kdoc: drop "sectionlist" Jonathan Corbet
@ 2025-07-11 5:50 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 21+ messages in thread
From: Mauro Carvalho Chehab @ 2025-07-11 5:50 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Akira Yokosawa
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
^ permalink raw reply [flat|nested] 21+ messages in thread
* [PATCH v2 04/12] docs: kdoc: Centralize handling of the item section list
2025-07-10 23:31 [PATCH v2 00/12] Thrash up the parser/output interface Jonathan Corbet
` (2 preceding siblings ...)
2025-07-10 23:31 ` [PATCH v2 03/12] docs: kdoc: drop "sectionlist" Jonathan Corbet
@ 2025-07-10 23:31 ` 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
` (8 subsequent siblings)
12 siblings, 1 reply; 21+ messages in thread
From: Jonathan Corbet @ 2025-07-10 23:31 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa,
Jonathan Corbet
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 <corbet@lwn.net>
---
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 = name
self.type = type
self.declaration_start_line = start_line
+ self.sections = {}
+ self.sections_start_lines = {}
#
# 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:
def __getitem__(self, key):
return self.get(key)
+
+ #
+ # Tracking of section information.
+ #
+ def set_sections(self, sections, start_lines):
+ self.sections = sections
+ self.section_start_lines = 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 = args.get('sections', {})
- section_start_lines = 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 += f'{self.lineprefix}**{section}**\n\n'
- 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 += "\n"
self.data += "\n"
@@ -635,23 +631,20 @@ class ManFormat(OutputFormat):
self.data += line + "\n"
def out_doc(self, fname, name, args):
- sections = args.get('sections', {})
-
if not self.check_doc(name, args):
return
self.data += f'.TH "{self.modulename}" 9 "{self.modulename}" "{self.man_date}" "API Manual" LINUX' + "\n"
- for section in sections:
+ for section, text in args.sections.items():
self.data += f'.SH "{section}"' + "\n"
- self.output_highlight(sections.get(section))
+ self.output_highlight(text)
def out_function(self, fname, name, args):
"""output function in man"""
parameterlist = args.get('parameterlist', [])
parameterdescs = args.get('parameterdescs', {})
- sections = args.get('sections', {})
self.data += f'.TH "{args["function"]}" 9 "{args["function"]}" "{self.man_date}" "Kernel Hacker\'s Manual" LINUX' + "\n"
@@ -692,15 +685,14 @@ class ManFormat(OutputFormat):
self.data += f'.IP "{parameter}" 12' + "\n"
self.output_highlight(parameterdescs.get(parameter_name, ""))
- for section in sections:
+ for section, text in args.sections.items():
self.data += f'.SH "{section.upper()}"' + "\n"
- self.output_highlight(sections[section])
+ self.output_highlight(text)
def out_enum(self, fname, name, args):
name = args.get('enum', '')
parameterlist = args.get('parameterlist', [])
- sections = args.get('sections', {})
self.data += f'.TH "{self.modulename}" 9 "enum {args["enum"]}" "{self.man_date}" "API Manual" LINUX' + "\n"
@@ -727,24 +719,23 @@ class ManFormat(OutputFormat):
self.data += f'.IP "{parameter}" 12' + "\n"
self.output_highlight(args['parameterdescs'].get(parameter_name, ""))
- for section in sections:
+ for section, text in args.sections.items():
self.data += f'.SH "{section}"' + "\n"
- self.output_highlight(sections[section])
+ self.output_highlight(text)
def out_typedef(self, fname, name, args):
module = self.modulename
typedef = args.get('typedef')
purpose = args.get('purpose')
- sections = args.get('sections', {})
self.data += f'.TH "{module}" 9 "{typedef}" "{self.man_date}" "API Manual" LINUX' + "\n"
self.data += ".SH NAME\n"
self.data += f"typedef {typedef} \\- {purpose}\n"
- for section in sections:
+ for section, text in args.sections.items():
self.data += f'.SH "{section}"' + "\n"
- self.output_highlight(sections.get(section))
+ self.output_highlight(text)
def out_struct(self, fname, name, args):
module = self.modulename
@@ -753,7 +744,6 @@ class ManFormat(OutputFormat):
purpose = args.get('purpose')
definition = args.get('definition')
parameterlist = args.get('parameterlist', [])
- sections = args.get('sections', {})
parameterdescs = args.get('parameterdescs', {})
self.data += f'.TH "{module}" 9 "{struct_type} {struct_name}" "{self.man_date}" "API Manual" LINUX' + "\n"
@@ -782,6 +772,6 @@ class ManFormat(OutputFormat):
self.data += f'.IP "{parameter}" 12' + "\n"
self.output_highlight(parameterdescs.get(parameter_name))
- for section in sections:
+ for section, text in args.sections.items():
self.data += 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 = KdocItem(name, dtype, self.entry.declaration_start_line, **args)
item.warnings = self.entry.warnings
- sections = item.get('sections', {})
-
# Drop empty sections
# TODO: improve empty sections logic to emit warnings
+ sections = 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)
self.entries.append(item)
@@ -824,8 +824,6 @@ class KernelDoc:
parameterdescs=self.entry.parameterdescs,
parametertypes=self.entry.parametertypes,
parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
- sections=self.entry.sections,
- section_start_lines=self.entry.section_start_lines,
purpose=self.entry.declaration_purpose)
def dump_enum(self, ln, proto):
@@ -908,8 +906,6 @@ class KernelDoc:
parameterlist=self.entry.parameterlist,
parameterdescs=self.entry.parameterdescs,
parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
- sections=self.entry.sections,
- section_start_lines=self.entry.section_start_lines,
purpose=self.entry.declaration_purpose)
def dump_declaration(self, ln, prototype):
@@ -1079,8 +1075,6 @@ class KernelDoc:
parameterdescs=self.entry.parameterdescs,
parametertypes=self.entry.parametertypes,
parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
- sections=self.entry.sections,
- section_start_lines=self.entry.section_start_lines,
purpose=self.entry.declaration_purpose,
func_macro=func_macro)
else:
@@ -1092,8 +1086,6 @@ class KernelDoc:
parameterdescs=self.entry.parameterdescs,
parametertypes=self.entry.parametertypes,
parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
- sections=self.entry.sections,
- section_start_lines=self.entry.section_start_lines,
purpose=self.entry.declaration_purpose,
func_macro=func_macro)
@@ -1137,8 +1129,6 @@ class KernelDoc:
parameterdescs=self.entry.parameterdescs,
parametertypes=self.entry.parametertypes,
parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
- sections=self.entry.sections,
- section_start_lines=self.entry.section_start_lines,
purpose=self.entry.declaration_purpose)
return
@@ -1159,8 +1149,6 @@ class KernelDoc:
self.output_declaration('typedef', declaration_name,
typedef=declaration_name,
- sections=self.entry.sections,
- section_start_lines=self.entry.section_start_lines,
purpose=self.entry.declaration_purpose)
return
@@ -1642,9 +1630,7 @@ class KernelDoc:
if doc_end.search(line):
self.dump_section()
- self.output_declaration("doc", self.entry.identifier,
- sections=self.entry.sections,
- section_start_lines=self.entry.section_start_lines)
+ self.output_declaration("doc", self.entry.identifier)
self.reset_state(ln)
elif doc_content.search(line):
--
2.49.0
^ permalink raw reply related [flat|nested] 21+ messages in thread* Re: [PATCH v2 04/12] docs: kdoc: Centralize handling of the item section list
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
0 siblings, 0 replies; 21+ messages in thread
From: Mauro Carvalho Chehab @ 2025-07-11 5:52 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Akira Yokosawa
Em Thu, 10 Jul 2025 17:31:34 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> 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 <corbet@lwn.net>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
> 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 = name
> self.type = type
> self.declaration_start_line = start_line
> + self.sections = {}
> + self.sections_start_lines = {}
> #
> # 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:
>
> def __getitem__(self, key):
> return self.get(key)
> +
> + #
> + # Tracking of section information.
> + #
> + def set_sections(self, sections, start_lines):
> + self.sections = sections
> + self.section_start_lines = 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 = args.get('sections', {})
> - section_start_lines = 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 += f'{self.lineprefix}**{section}**\n\n'
>
> - 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 += "\n"
> self.data += "\n"
>
> @@ -635,23 +631,20 @@ class ManFormat(OutputFormat):
> self.data += line + "\n"
>
> def out_doc(self, fname, name, args):
> - sections = args.get('sections', {})
> -
> if not self.check_doc(name, args):
> return
>
> self.data += f'.TH "{self.modulename}" 9 "{self.modulename}" "{self.man_date}" "API Manual" LINUX' + "\n"
>
> - for section in sections:
> + for section, text in args.sections.items():
> self.data += f'.SH "{section}"' + "\n"
> - self.output_highlight(sections.get(section))
> + self.output_highlight(text)
>
> def out_function(self, fname, name, args):
> """output function in man"""
>
> parameterlist = args.get('parameterlist', [])
> parameterdescs = args.get('parameterdescs', {})
> - sections = args.get('sections', {})
>
> self.data += f'.TH "{args["function"]}" 9 "{args["function"]}" "{self.man_date}" "Kernel Hacker\'s Manual" LINUX' + "\n"
>
> @@ -692,15 +685,14 @@ class ManFormat(OutputFormat):
> self.data += f'.IP "{parameter}" 12' + "\n"
> self.output_highlight(parameterdescs.get(parameter_name, ""))
>
> - for section in sections:
> + for section, text in args.sections.items():
> self.data += f'.SH "{section.upper()}"' + "\n"
> - self.output_highlight(sections[section])
> + self.output_highlight(text)
>
> def out_enum(self, fname, name, args):
>
> name = args.get('enum', '')
> parameterlist = args.get('parameterlist', [])
> - sections = args.get('sections', {})
>
> self.data += f'.TH "{self.modulename}" 9 "enum {args["enum"]}" "{self.man_date}" "API Manual" LINUX' + "\n"
>
> @@ -727,24 +719,23 @@ class ManFormat(OutputFormat):
> self.data += f'.IP "{parameter}" 12' + "\n"
> self.output_highlight(args['parameterdescs'].get(parameter_name, ""))
>
> - for section in sections:
> + for section, text in args.sections.items():
> self.data += f'.SH "{section}"' + "\n"
> - self.output_highlight(sections[section])
> + self.output_highlight(text)
>
> def out_typedef(self, fname, name, args):
> module = self.modulename
> typedef = args.get('typedef')
> purpose = args.get('purpose')
> - sections = args.get('sections', {})
>
> self.data += f'.TH "{module}" 9 "{typedef}" "{self.man_date}" "API Manual" LINUX' + "\n"
>
> self.data += ".SH NAME\n"
> self.data += f"typedef {typedef} \\- {purpose}\n"
>
> - for section in sections:
> + for section, text in args.sections.items():
> self.data += f'.SH "{section}"' + "\n"
> - self.output_highlight(sections.get(section))
> + self.output_highlight(text)
>
> def out_struct(self, fname, name, args):
> module = self.modulename
> @@ -753,7 +744,6 @@ class ManFormat(OutputFormat):
> purpose = args.get('purpose')
> definition = args.get('definition')
> parameterlist = args.get('parameterlist', [])
> - sections = args.get('sections', {})
> parameterdescs = args.get('parameterdescs', {})
>
> self.data += f'.TH "{module}" 9 "{struct_type} {struct_name}" "{self.man_date}" "API Manual" LINUX' + "\n"
> @@ -782,6 +772,6 @@ class ManFormat(OutputFormat):
> self.data += f'.IP "{parameter}" 12' + "\n"
> self.output_highlight(parameterdescs.get(parameter_name))
>
> - for section in sections:
> + for section, text in args.sections.items():
> self.data += 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 = KdocItem(name, dtype, self.entry.declaration_start_line, **args)
> item.warnings = self.entry.warnings
>
> - sections = item.get('sections', {})
> -
> # Drop empty sections
> # TODO: improve empty sections logic to emit warnings
> + sections = 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)
>
> self.entries.append(item)
>
> @@ -824,8 +824,6 @@ class KernelDoc:
> parameterdescs=self.entry.parameterdescs,
> parametertypes=self.entry.parametertypes,
> parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
> - sections=self.entry.sections,
> - section_start_lines=self.entry.section_start_lines,
> purpose=self.entry.declaration_purpose)
>
> def dump_enum(self, ln, proto):
> @@ -908,8 +906,6 @@ class KernelDoc:
> parameterlist=self.entry.parameterlist,
> parameterdescs=self.entry.parameterdescs,
> parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
> - sections=self.entry.sections,
> - section_start_lines=self.entry.section_start_lines,
> purpose=self.entry.declaration_purpose)
>
> def dump_declaration(self, ln, prototype):
> @@ -1079,8 +1075,6 @@ class KernelDoc:
> parameterdescs=self.entry.parameterdescs,
> parametertypes=self.entry.parametertypes,
> parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
> - sections=self.entry.sections,
> - section_start_lines=self.entry.section_start_lines,
> purpose=self.entry.declaration_purpose,
> func_macro=func_macro)
> else:
> @@ -1092,8 +1086,6 @@ class KernelDoc:
> parameterdescs=self.entry.parameterdescs,
> parametertypes=self.entry.parametertypes,
> parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
> - sections=self.entry.sections,
> - section_start_lines=self.entry.section_start_lines,
> purpose=self.entry.declaration_purpose,
> func_macro=func_macro)
>
> @@ -1137,8 +1129,6 @@ class KernelDoc:
> parameterdescs=self.entry.parameterdescs,
> parametertypes=self.entry.parametertypes,
> parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
> - sections=self.entry.sections,
> - section_start_lines=self.entry.section_start_lines,
> purpose=self.entry.declaration_purpose)
> return
>
> @@ -1159,8 +1149,6 @@ class KernelDoc:
>
> self.output_declaration('typedef', declaration_name,
> typedef=declaration_name,
> - sections=self.entry.sections,
> - section_start_lines=self.entry.section_start_lines,
> purpose=self.entry.declaration_purpose)
> return
>
> @@ -1642,9 +1630,7 @@ class KernelDoc:
>
> if doc_end.search(line):
> self.dump_section()
> - self.output_declaration("doc", self.entry.identifier,
> - sections=self.entry.sections,
> - section_start_lines=self.entry.section_start_lines)
> + self.output_declaration("doc", self.entry.identifier)
> self.reset_state(ln)
>
> elif doc_content.search(line):
Thanks,
Mauro
^ permalink raw reply [flat|nested] 21+ messages in thread
* [PATCH v2 05/12] docs: kdoc: remove the "struct_actual" machinery
2025-07-10 23:31 [PATCH v2 00/12] Thrash up the parser/output interface Jonathan Corbet
` (3 preceding siblings ...)
2025-07-10 23:31 ` [PATCH v2 04/12] docs: kdoc: Centralize handling of the item section list Jonathan Corbet
@ 2025-07-10 23:31 ` Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 06/12] docs: kdoc: use self.entry.parameterlist directly in check_sections() Jonathan Corbet
` (7 subsequent siblings)
12 siblings, 0 replies; 21+ messages in thread
From: Jonathan Corbet @ 2025-07-10 23:31 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa,
Jonathan Corbet
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 <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
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:
self._contents = []
self.sectcheck = ""
- self.struct_actual = ""
self.prototype = ""
self.warnings = []
@@ -366,15 +365,6 @@ class KernelDoc:
org_arg = KernRe(r'\s\s+').sub(' ', org_arg)
self.entry.parametertypes[param] = org_arg
- def save_struct_actual(self, actual):
- """
- Strip all spaces from the actual param so that it looks like
- one string item.
- """
-
- actual = KernRe(r'\s*').sub("", actual, count=1)
-
- self.entry.struct_actual += actual + " "
def create_parameter_list(self, ln, decl_type, args,
splitter, declaration_name):
@@ -420,7 +410,6 @@ class KernelDoc:
param = arg
dtype = KernRe(r'([^\(]+\(\*?)\s*' + re.escape(param)).sub(r'\1', arg)
- self.save_struct_actual(param)
self.push_parameter(ln, decl_type, param, dtype,
arg, declaration_name)
@@ -437,7 +426,6 @@ class KernelDoc:
dtype = KernRe(r'([^\(]+\(\*?)\s*' + re.escape(param)).sub(r'\1', arg)
- self.save_struct_actual(param)
self.push_parameter(ln, decl_type, param, dtype,
arg, declaration_name)
@@ -470,7 +458,6 @@ class KernelDoc:
param = r.group(1)
- 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
if dtype != "": # 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)
@@ -499,24 +484,11 @@ class KernelDoc:
sects = sectcheck.split()
prms = prmscheck.split()
- err = False
for sx in range(len(sects)): # pylint: disable=C0200
err = True
for px in range(len(prms)): # pylint: disable=C0200
- prm_clean = prms[px]
- prm_clean = KernRe(r'\[.*\]').sub('', prm_clean)
- prm_clean = 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 = KernRe(r'\[.*').sub('', prm_clean)
-
- if prm_clean == sects[sx]:
+ if prms[px] == sects[sx]:
err = False
break
@@ -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.parameterlist))
# Adjust declaration for better display
declaration = KernRe(r'([\{;])').sub(r'\1\n', declaration)
--
2.49.0
^ permalink raw reply related [flat|nested] 21+ messages in thread* [PATCH v2 06/12] docs: kdoc: use self.entry.parameterlist directly in check_sections()
2025-07-10 23:31 [PATCH v2 00/12] Thrash up the parser/output interface Jonathan Corbet
` (4 preceding siblings ...)
2025-07-10 23:31 ` [PATCH v2 05/12] docs: kdoc: remove the "struct_actual" machinery Jonathan Corbet
@ 2025-07-10 23:31 ` Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 07/12] docs: kdoc: Coalesce parameter-list handling Jonathan Corbet
` (6 subsequent siblings)
12 siblings, 0 replies; 21+ messages in thread
From: Jonathan Corbet @ 2025-07-10 23:31 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa,
Jonathan Corbet
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 <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
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)
- def check_sections(self, ln, decl_name, decl_type, sectcheck, prmscheck):
+ def check_sections(self, ln, decl_name, decl_type, sectcheck):
"""
Check for errors inside sections, emitting warnings if not found
parameters are described.
"""
sects = sectcheck.split()
- prms = prmscheck.split()
for sx in range(len(sects)): # pylint: disable=C0200
err = True
- for px in range(len(prms)): # pylint: disable=C0200
- if prms[px] == sects[sx]:
+ for param in self.entry.parameterlist:
+ if param == sects[sx]:
err = False
break
@@ -753,8 +752,7 @@ class KernelDoc:
self.create_parameter_list(ln, decl_type, members, ';',
declaration_name)
- self.check_sections(ln, declaration_name, decl_type,
- self.entry.sectcheck, ' '.join(self.entry.parameterlist))
+ self.check_sections(ln, declaration_name, decl_type, self.entry.sectcheck)
# Adjust declaration for better display
declaration = 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
- prms = " ".join(self.entry.parameterlist)
- self.check_sections(ln, declaration_name, "function",
- self.entry.sectcheck, prms)
+ self.check_sections(ln, declaration_name, "function", self.entry.sectcheck)
self.check_return_section(ln, declaration_name, return_type)
--
2.49.0
^ permalink raw reply related [flat|nested] 21+ messages in thread* [PATCH v2 07/12] docs: kdoc: Coalesce parameter-list handling
2025-07-10 23:31 [PATCH v2 00/12] Thrash up the parser/output interface Jonathan Corbet
` (5 preceding siblings ...)
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 ` Jonathan Corbet
2025-07-11 5:54 ` Mauro Carvalho Chehab
2025-07-10 23:31 ` [PATCH v2 08/12] docs: kdoc: Regularize the use of the declaration name Jonathan Corbet
` (5 subsequent siblings)
12 siblings, 1 reply; 21+ messages in thread
From: Jonathan Corbet @ 2025-07-10 23:31 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa,
Jonathan Corbet
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 <corbet@lwn.net>
---
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 = start_line
self.sections = {}
self.sections_start_lines = {}
+ self.parameterlist = self.parameterdesc_start_lines = []
+ self.parameterdescs = {}
+ self.parametertypes = {}
#
# 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)
#
- # Tracking of section information.
+ # Tracking of section and parameter information.
#
def set_sections(self, sections, start_lines):
self.sections = sections
self.section_start_lines = start_lines
+
+ def set_params(self, names, descs, types, starts):
+ self.parameterlist = names
+ self.parameterdescs = descs
+ self.parametertypes = types
+ self.parameterdesc_start_lines = 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 = args['functiontype'] + " "
signature += args['function'] + " ("
- parameterlist = args.get('parameterlist', [])
- parameterdescs = args.get('parameterdescs', {})
- parameterdesc_start_lines = args.get('parameterdesc_start_lines', {})
-
ln = args.get('declaration_start_line', 0)
-
count = 0
- for parameter in parameterlist:
+ for parameter in args.parameterlist:
if count != 0:
signature += ", "
count += 1
- dtype = args['parametertypes'].get(parameter, "")
+ dtype = args.parametertypes.get(parameter, "")
if function_pointer.search(dtype):
signature += function_pointer.group(1) + parameter + function_pointer.group(3)
@@ -419,26 +414,26 @@ class RestFormat(OutputFormat):
# function prototypes apart
self.lineprefix = " "
- if parameterlist:
+ if args.parameterlist:
self.data += ".. container:: kernelindent\n\n"
self.data += f"{self.lineprefix}**Parameters**\n\n"
- for parameter in parameterlist:
+ for parameter in args.parameterlist:
parameter_name = KernRe(r'\[.*').sub('', parameter)
- dtype = args['parametertypes'].get(parameter, "")
+ dtype = args.parametertypes.get(parameter, "")
if dtype:
self.data += f"{self.lineprefix}``{dtype}``\n"
else:
self.data += f"{self.lineprefix}``{parameter}``\n"
- self.print_lineno(parameterdesc_start_lines.get(parameter_name, 0))
+ self.print_lineno(args.parameterdesc_start_lines.get(parameter_name, 0))
self.lineprefix = " "
- if parameter_name in parameterdescs and \
- parameterdescs[parameter_name] != KernelDoc.undescribed:
+ if parameter_name in args.parameterdescs and \
+ args.parameterdescs[parameter_name] != KernelDoc.undescribed:
- self.output_highlight(parameterdescs[parameter_name])
+ self.output_highlight(args.parameterdescs[parameter_name])
self.data += "\n"
else:
self.data += f"{self.lineprefix}*undescribed*\n\n"
@@ -451,8 +446,6 @@ class RestFormat(OutputFormat):
oldprefix = self.lineprefix
name = args.get('enum', '')
- parameterlist = args.get('parameterlist', [])
- parameterdescs = args.get('parameterdescs', {})
ln = args.get('declaration_start_line', 0)
self.data += f"\n\n.. c:enum:: {name}\n\n"
@@ -467,11 +460,11 @@ class RestFormat(OutputFormat):
self.lineprefix = outer + " "
self.data += f"{outer}**Constants**\n\n"
- for parameter in parameterlist:
+ for parameter in args.parameterlist:
self.data += f"{outer}``{parameter}``\n"
- if parameterdescs.get(parameter, '') != KernelDoc.undescribed:
- self.output_highlight(parameterdescs[parameter])
+ if args.parameterdescs.get(parameter, '') != KernelDoc.undescribed:
+ self.output_highlight(args.parameterdescs[parameter])
else:
self.data += f"{self.lineprefix}*undescribed*\n\n"
self.data += "\n"
@@ -505,10 +498,6 @@ class RestFormat(OutputFormat):
dtype = args.get('type', "struct")
ln = args.get('declaration_start_line', 0)
- parameterlist = args.get('parameterlist', [])
- parameterdescs = args.get('parameterdescs', {})
- parameterdesc_start_lines = args.get('parameterdesc_start_lines', {})
-
self.data += f"\n\n.. c:{dtype}:: {name}\n\n"
self.print_lineno(ln)
@@ -531,21 +520,21 @@ class RestFormat(OutputFormat):
self.lineprefix = " "
self.data += f"{self.lineprefix}**Members**\n\n"
- for parameter in parameterlist:
+ for parameter in args.parameterlist:
if not parameter or parameter.startswith("#"):
continue
parameter_name = parameter.split("[", maxsplit=1)[0]
- if parameterdescs.get(parameter_name) == KernelDoc.undescribed:
+ if args.parameterdescs.get(parameter_name) == KernelDoc.undescribed:
continue
- self.print_lineno(parameterdesc_start_lines.get(parameter_name, 0))
+ self.print_lineno(args.parameterdesc_start_lines.get(parameter_name, 0))
self.data += f"{self.lineprefix}``{parameter}``\n"
self.lineprefix = " "
- self.output_highlight(parameterdescs[parameter_name])
+ self.output_highlight(args.parameterdescs[parameter_name])
self.lineprefix = " "
self.data += "\n"
@@ -643,9 +632,6 @@ class ManFormat(OutputFormat):
def out_function(self, fname, name, args):
"""output function in man"""
- parameterlist = args.get('parameterlist', [])
- parameterdescs = args.get('parameterdescs', {})
-
self.data += f'.TH "{args["function"]}" 9 "{args["function"]}" "{self.man_date}" "Kernel Hacker\'s Manual" LINUX' + "\n"
self.data += ".SH NAME\n"
@@ -661,11 +647,11 @@ class ManFormat(OutputFormat):
parenth = "("
post = ","
- for parameter in parameterlist:
- if count == len(parameterlist) - 1:
+ for parameter in args.parameterlist:
+ if count == len(args.parameterlist) - 1:
post = ");"
- dtype = args['parametertypes'].get(parameter, "")
+ dtype = args.parametertypes.get(parameter, "")
if function_pointer.match(dtype):
# Pointer-to-function
self.data += f'".BI "{parenth}{function_pointer.group(1)}" " ") ({function_pointer.group(2)}){post}"' + "\n"
@@ -676,14 +662,14 @@ class ManFormat(OutputFormat):
count += 1
parenth = ""
- if parameterlist:
+ if args.parameterlist:
self.data += ".SH ARGUMENTS\n"
- for parameter in parameterlist:
+ for parameter in args.parameterlist:
parameter_name = re.sub(r'\[.*', '', parameter)
self.data += f'.IP "{parameter}" 12' + "\n"
- self.output_highlight(parameterdescs.get(parameter_name, ""))
+ self.output_highlight(args.parameterdescs.get(parameter_name, ""))
for section, text in args.sections.items():
self.data += f'.SH "{section.upper()}"' + "\n"
@@ -692,7 +678,6 @@ class ManFormat(OutputFormat):
def out_enum(self, fname, name, args):
name = args.get('enum', '')
- parameterlist = args.get('parameterlist', [])
self.data += f'.TH "{self.modulename}" 9 "enum {args["enum"]}" "{self.man_date}" "API Manual" LINUX' + "\n"
@@ -703,9 +688,9 @@ class ManFormat(OutputFormat):
self.data += f"enum {args['enum']}" + " {\n"
count = 0
- for parameter in parameterlist:
+ for parameter in args.parameterlist:
self.data += f'.br\n.BI " {parameter}"' + "\n"
- if count == len(parameterlist) - 1:
+ if count == len(args.parameterlist) - 1:
self.data += "\n};\n"
else:
self.data += ", \n.br\n"
@@ -714,10 +699,10 @@ class ManFormat(OutputFormat):
self.data += ".SH Constants\n"
- for parameter in parameterlist:
+ for parameter in args.parameterlist:
parameter_name = KernRe(r'\[.*').sub('', parameter)
self.data += f'.IP "{parameter}" 12' + "\n"
- self.output_highlight(args['parameterdescs'].get(parameter_name, ""))
+ self.output_highlight(args.parameterdescs.get(parameter_name, ""))
for section, text in args.sections.items():
self.data += f'.SH "{section}"' + "\n"
@@ -743,8 +728,6 @@ class ManFormat(OutputFormat):
struct_name = args.get('struct')
purpose = args.get('purpose')
definition = args.get('definition')
- parameterlist = args.get('parameterlist', [])
- parameterdescs = args.get('parameterdescs', {})
self.data += f'.TH "{module}" 9 "{struct_type} {struct_name}" "{self.man_date}" "API Manual" LINUX' + "\n"
@@ -760,17 +743,17 @@ class ManFormat(OutputFormat):
self.data += f'.BI "{declaration}\n' + "};\n.br\n\n"
self.data += ".SH Members\n"
- for parameter in parameterlist:
+ for parameter in args.parameterlist:
if parameter.startswith("#"):
continue
parameter_name = re.sub(r"\[.*", "", parameter)
- if parameterdescs.get(parameter_name) == KernelDoc.undescribed:
+ if args.parameterdescs.get(parameter_name) == KernelDoc.undescribed:
continue
self.data += f'.IP "{parameter}" 12' + "\n"
- self.output_highlight(parameterdescs.get(parameter_name))
+ self.output_highlight(args.parameterdescs.get(parameter_name))
for section, text in args.sections.items():
self.data += 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.parameterdescs,
+ self.entry.parametertypes,
+ self.entry.parameterdesc_start_lines)
self.entries.append(item)
self.config.log.debug("Output: %s:%s = %s", dtype, name, pformat(args))
@@ -790,10 +792,6 @@ class KernelDoc:
self.output_declaration(decl_type, declaration_name,
struct=declaration_name,
definition=declaration,
- parameterlist=self.entry.parameterlist,
- parameterdescs=self.entry.parameterdescs,
- parametertypes=self.entry.parametertypes,
- parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
purpose=self.entry.declaration_purpose)
def dump_enum(self, ln, proto):
@@ -873,9 +871,6 @@ class KernelDoc:
self.output_declaration('enum', declaration_name,
enum=declaration_name,
- parameterlist=self.entry.parameterlist,
- parameterdescs=self.entry.parameterdescs,
- parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
purpose=self.entry.declaration_purpose)
def dump_declaration(self, ln, prototype):
@@ -1039,10 +1034,6 @@ class KernelDoc:
function=declaration_name,
typedef=True,
functiontype=return_type,
- parameterlist=self.entry.parameterlist,
- parameterdescs=self.entry.parameterdescs,
- parametertypes=self.entry.parametertypes,
- parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
purpose=self.entry.declaration_purpose,
func_macro=func_macro)
else:
@@ -1050,10 +1041,6 @@ class KernelDoc:
function=declaration_name,
typedef=False,
functiontype=return_type,
- parameterlist=self.entry.parameterlist,
- parameterdescs=self.entry.parameterdescs,
- parametertypes=self.entry.parametertypes,
- parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
purpose=self.entry.declaration_purpose,
func_macro=func_macro)
@@ -1093,10 +1080,6 @@ class KernelDoc:
function=declaration_name,
typedef=True,
functiontype=return_type,
- parameterlist=self.entry.parameterlist,
- parameterdescs=self.entry.parameterdescs,
- parametertypes=self.entry.parametertypes,
- parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
purpose=self.entry.declaration_purpose)
return
--
2.49.0
^ permalink raw reply related [flat|nested] 21+ messages in thread* Re: [PATCH v2 07/12] docs: kdoc: Coalesce parameter-list handling
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
0 siblings, 1 reply; 21+ messages in thread
From: Mauro Carvalho Chehab @ 2025-07-11 5:54 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Akira Yokosawa
Em Thu, 10 Jul 2025 17:31:37 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> 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 <corbet@lwn.net>
> ---
> 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 = start_line
> self.sections = {}
> self.sections_start_lines = {}
> + self.parameterlist = self.parameterdesc_start_lines = []
Please split it on two lines as well. With that, feel free to add:
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> + self.parameterdescs = {}
> + self.parametertypes = {}
> #
> # 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)
>
> #
> - # Tracking of section information.
> + # Tracking of section and parameter information.
> #
> def set_sections(self, sections, start_lines):
> self.sections = sections
> self.section_start_lines = start_lines
> +
> + def set_params(self, names, descs, types, starts):
> + self.parameterlist = names
> + self.parameterdescs = descs
> + self.parametertypes = types
> + self.parameterdesc_start_lines = 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 = args['functiontype'] + " "
> signature += args['function'] + " ("
>
> - parameterlist = args.get('parameterlist', [])
> - parameterdescs = args.get('parameterdescs', {})
> - parameterdesc_start_lines = args.get('parameterdesc_start_lines', {})
> -
> ln = args.get('declaration_start_line', 0)
> -
> count = 0
> - for parameter in parameterlist:
> + for parameter in args.parameterlist:
> if count != 0:
> signature += ", "
> count += 1
> - dtype = args['parametertypes'].get(parameter, "")
> + dtype = args.parametertypes.get(parameter, "")
>
> if function_pointer.search(dtype):
> signature += function_pointer.group(1) + parameter + function_pointer.group(3)
> @@ -419,26 +414,26 @@ class RestFormat(OutputFormat):
> # function prototypes apart
> self.lineprefix = " "
>
> - if parameterlist:
> + if args.parameterlist:
> self.data += ".. container:: kernelindent\n\n"
> self.data += f"{self.lineprefix}**Parameters**\n\n"
>
> - for parameter in parameterlist:
> + for parameter in args.parameterlist:
> parameter_name = KernRe(r'\[.*').sub('', parameter)
> - dtype = args['parametertypes'].get(parameter, "")
> + dtype = args.parametertypes.get(parameter, "")
>
> if dtype:
> self.data += f"{self.lineprefix}``{dtype}``\n"
> else:
> self.data += f"{self.lineprefix}``{parameter}``\n"
>
> - self.print_lineno(parameterdesc_start_lines.get(parameter_name, 0))
> + self.print_lineno(args.parameterdesc_start_lines.get(parameter_name, 0))
>
> self.lineprefix = " "
> - if parameter_name in parameterdescs and \
> - parameterdescs[parameter_name] != KernelDoc.undescribed:
> + if parameter_name in args.parameterdescs and \
> + args.parameterdescs[parameter_name] != KernelDoc.undescribed:
>
> - self.output_highlight(parameterdescs[parameter_name])
> + self.output_highlight(args.parameterdescs[parameter_name])
> self.data += "\n"
> else:
> self.data += f"{self.lineprefix}*undescribed*\n\n"
> @@ -451,8 +446,6 @@ class RestFormat(OutputFormat):
>
> oldprefix = self.lineprefix
> name = args.get('enum', '')
> - parameterlist = args.get('parameterlist', [])
> - parameterdescs = args.get('parameterdescs', {})
> ln = args.get('declaration_start_line', 0)
>
> self.data += f"\n\n.. c:enum:: {name}\n\n"
> @@ -467,11 +460,11 @@ class RestFormat(OutputFormat):
> self.lineprefix = outer + " "
> self.data += f"{outer}**Constants**\n\n"
>
> - for parameter in parameterlist:
> + for parameter in args.parameterlist:
> self.data += f"{outer}``{parameter}``\n"
>
> - if parameterdescs.get(parameter, '') != KernelDoc.undescribed:
> - self.output_highlight(parameterdescs[parameter])
> + if args.parameterdescs.get(parameter, '') != KernelDoc.undescribed:
> + self.output_highlight(args.parameterdescs[parameter])
> else:
> self.data += f"{self.lineprefix}*undescribed*\n\n"
> self.data += "\n"
> @@ -505,10 +498,6 @@ class RestFormat(OutputFormat):
> dtype = args.get('type', "struct")
> ln = args.get('declaration_start_line', 0)
>
> - parameterlist = args.get('parameterlist', [])
> - parameterdescs = args.get('parameterdescs', {})
> - parameterdesc_start_lines = args.get('parameterdesc_start_lines', {})
> -
> self.data += f"\n\n.. c:{dtype}:: {name}\n\n"
>
> self.print_lineno(ln)
> @@ -531,21 +520,21 @@ class RestFormat(OutputFormat):
>
> self.lineprefix = " "
> self.data += f"{self.lineprefix}**Members**\n\n"
> - for parameter in parameterlist:
> + for parameter in args.parameterlist:
> if not parameter or parameter.startswith("#"):
> continue
>
> parameter_name = parameter.split("[", maxsplit=1)[0]
>
> - if parameterdescs.get(parameter_name) == KernelDoc.undescribed:
> + if args.parameterdescs.get(parameter_name) == KernelDoc.undescribed:
> continue
>
> - self.print_lineno(parameterdesc_start_lines.get(parameter_name, 0))
> + self.print_lineno(args.parameterdesc_start_lines.get(parameter_name, 0))
>
> self.data += f"{self.lineprefix}``{parameter}``\n"
>
> self.lineprefix = " "
> - self.output_highlight(parameterdescs[parameter_name])
> + self.output_highlight(args.parameterdescs[parameter_name])
> self.lineprefix = " "
>
> self.data += "\n"
> @@ -643,9 +632,6 @@ class ManFormat(OutputFormat):
> def out_function(self, fname, name, args):
> """output function in man"""
>
> - parameterlist = args.get('parameterlist', [])
> - parameterdescs = args.get('parameterdescs', {})
> -
> self.data += f'.TH "{args["function"]}" 9 "{args["function"]}" "{self.man_date}" "Kernel Hacker\'s Manual" LINUX' + "\n"
>
> self.data += ".SH NAME\n"
> @@ -661,11 +647,11 @@ class ManFormat(OutputFormat):
> parenth = "("
> post = ","
>
> - for parameter in parameterlist:
> - if count == len(parameterlist) - 1:
> + for parameter in args.parameterlist:
> + if count == len(args.parameterlist) - 1:
> post = ");"
>
> - dtype = args['parametertypes'].get(parameter, "")
> + dtype = args.parametertypes.get(parameter, "")
> if function_pointer.match(dtype):
> # Pointer-to-function
> self.data += f'".BI "{parenth}{function_pointer.group(1)}" " ") ({function_pointer.group(2)}){post}"' + "\n"
> @@ -676,14 +662,14 @@ class ManFormat(OutputFormat):
> count += 1
> parenth = ""
>
> - if parameterlist:
> + if args.parameterlist:
> self.data += ".SH ARGUMENTS\n"
>
> - for parameter in parameterlist:
> + for parameter in args.parameterlist:
> parameter_name = re.sub(r'\[.*', '', parameter)
>
> self.data += f'.IP "{parameter}" 12' + "\n"
> - self.output_highlight(parameterdescs.get(parameter_name, ""))
> + self.output_highlight(args.parameterdescs.get(parameter_name, ""))
>
> for section, text in args.sections.items():
> self.data += f'.SH "{section.upper()}"' + "\n"
> @@ -692,7 +678,6 @@ class ManFormat(OutputFormat):
> def out_enum(self, fname, name, args):
>
> name = args.get('enum', '')
> - parameterlist = args.get('parameterlist', [])
>
> self.data += f'.TH "{self.modulename}" 9 "enum {args["enum"]}" "{self.man_date}" "API Manual" LINUX' + "\n"
>
> @@ -703,9 +688,9 @@ class ManFormat(OutputFormat):
> self.data += f"enum {args['enum']}" + " {\n"
>
> count = 0
> - for parameter in parameterlist:
> + for parameter in args.parameterlist:
> self.data += f'.br\n.BI " {parameter}"' + "\n"
> - if count == len(parameterlist) - 1:
> + if count == len(args.parameterlist) - 1:
> self.data += "\n};\n"
> else:
> self.data += ", \n.br\n"
> @@ -714,10 +699,10 @@ class ManFormat(OutputFormat):
>
> self.data += ".SH Constants\n"
>
> - for parameter in parameterlist:
> + for parameter in args.parameterlist:
> parameter_name = KernRe(r'\[.*').sub('', parameter)
> self.data += f'.IP "{parameter}" 12' + "\n"
> - self.output_highlight(args['parameterdescs'].get(parameter_name, ""))
> + self.output_highlight(args.parameterdescs.get(parameter_name, ""))
>
> for section, text in args.sections.items():
> self.data += f'.SH "{section}"' + "\n"
> @@ -743,8 +728,6 @@ class ManFormat(OutputFormat):
> struct_name = args.get('struct')
> purpose = args.get('purpose')
> definition = args.get('definition')
> - parameterlist = args.get('parameterlist', [])
> - parameterdescs = args.get('parameterdescs', {})
>
> self.data += f'.TH "{module}" 9 "{struct_type} {struct_name}" "{self.man_date}" "API Manual" LINUX' + "\n"
>
> @@ -760,17 +743,17 @@ class ManFormat(OutputFormat):
> self.data += f'.BI "{declaration}\n' + "};\n.br\n\n"
>
> self.data += ".SH Members\n"
> - for parameter in parameterlist:
> + for parameter in args.parameterlist:
> if parameter.startswith("#"):
> continue
>
> parameter_name = re.sub(r"\[.*", "", parameter)
>
> - if parameterdescs.get(parameter_name) == KernelDoc.undescribed:
> + if args.parameterdescs.get(parameter_name) == KernelDoc.undescribed:
> continue
>
> self.data += f'.IP "{parameter}" 12' + "\n"
> - self.output_highlight(parameterdescs.get(parameter_name))
> + self.output_highlight(args.parameterdescs.get(parameter_name))
>
> for section, text in args.sections.items():
> self.data += 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.parameterdescs,
> + self.entry.parametertypes,
> + self.entry.parameterdesc_start_lines)
> self.entries.append(item)
>
> self.config.log.debug("Output: %s:%s = %s", dtype, name, pformat(args))
> @@ -790,10 +792,6 @@ class KernelDoc:
> self.output_declaration(decl_type, declaration_name,
> struct=declaration_name,
> definition=declaration,
> - parameterlist=self.entry.parameterlist,
> - parameterdescs=self.entry.parameterdescs,
> - parametertypes=self.entry.parametertypes,
> - parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
> purpose=self.entry.declaration_purpose)
>
> def dump_enum(self, ln, proto):
> @@ -873,9 +871,6 @@ class KernelDoc:
>
> self.output_declaration('enum', declaration_name,
> enum=declaration_name,
> - parameterlist=self.entry.parameterlist,
> - parameterdescs=self.entry.parameterdescs,
> - parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
> purpose=self.entry.declaration_purpose)
>
> def dump_declaration(self, ln, prototype):
> @@ -1039,10 +1034,6 @@ class KernelDoc:
> function=declaration_name,
> typedef=True,
> functiontype=return_type,
> - parameterlist=self.entry.parameterlist,
> - parameterdescs=self.entry.parameterdescs,
> - parametertypes=self.entry.parametertypes,
> - parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
> purpose=self.entry.declaration_purpose,
> func_macro=func_macro)
> else:
> @@ -1050,10 +1041,6 @@ class KernelDoc:
> function=declaration_name,
> typedef=False,
> functiontype=return_type,
> - parameterlist=self.entry.parameterlist,
> - parameterdescs=self.entry.parameterdescs,
> - parametertypes=self.entry.parametertypes,
> - parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
> purpose=self.entry.declaration_purpose,
> func_macro=func_macro)
>
> @@ -1093,10 +1080,6 @@ class KernelDoc:
> function=declaration_name,
> typedef=True,
> functiontype=return_type,
> - parameterlist=self.entry.parameterlist,
> - parameterdescs=self.entry.parameterdescs,
> - parametertypes=self.entry.parametertypes,
> - parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
> purpose=self.entry.declaration_purpose)
> return
>
Thanks,
Mauro
^ permalink raw reply [flat|nested] 21+ messages in thread* Re: [PATCH v2 07/12] docs: kdoc: Coalesce parameter-list handling
2025-07-11 5:54 ` Mauro Carvalho Chehab
@ 2025-07-11 12:45 ` Jonathan Corbet
0 siblings, 0 replies; 21+ messages in thread
From: Jonathan Corbet @ 2025-07-11 12:45 UTC (permalink / raw)
To: Mauro Carvalho Chehab; +Cc: linux-doc, linux-kernel, Akira Yokosawa
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> Em Thu, 10 Jul 2025 17:31:37 -0600
> Jonathan Corbet <corbet@lwn.net> escreveu:
>
>> 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 <corbet@lwn.net>
>> ---
>> 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 = start_line
>> self.sections = {}
>> self.sections_start_lines = {}
>
>> + self.parameterlist = self.parameterdesc_start_lines = []
>
> Please split it on two lines as well. With that, feel free to add:
>
> Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Weird, I was sure I did that...will do it again...
Thanks,
jon
^ permalink raw reply [flat|nested] 21+ messages in thread
* [PATCH v2 08/12] docs: kdoc: Regularize the use of the declaration name
2025-07-10 23:31 [PATCH v2 00/12] Thrash up the parser/output interface Jonathan Corbet
` (6 preceding siblings ...)
2025-07-10 23:31 ` [PATCH v2 07/12] docs: kdoc: Coalesce parameter-list handling Jonathan Corbet
@ 2025-07-10 23:31 ` Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 09/12] docs: kdoc: straighten up dump_declaration() Jonathan Corbet
` (4 subsequent siblings)
12 siblings, 0 replies; 21+ messages in thread
From: Jonathan Corbet @ 2025-07-10 23:31 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa,
Jonathan Corbet
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 <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
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):
func_macro = args.get('func_macro', False)
if func_macro:
- signature = args['function']
+ signature = name
else:
if args.get('functiontype'):
signature = args['functiontype'] + " "
- signature += args['function'] + " ("
+ signature += name + " ("
ln = args.get('declaration_start_line', 0)
count = 0
@@ -391,7 +391,7 @@ class RestFormat(OutputFormat):
self.print_lineno(ln)
if args.get('typedef') or not args.get('functiontype'):
- self.data += f".. c:macro:: {args['function']}\n\n"
+ self.data += f".. c:macro:: {name}\n\n"
if args.get('typedef'):
self.data += " **Typedef**: "
@@ -445,7 +445,6 @@ class RestFormat(OutputFormat):
def out_enum(self, fname, name, args):
oldprefix = self.lineprefix
- name = args.get('enum', '')
ln = args.get('declaration_start_line', 0)
self.data += f"\n\n.. c:enum:: {name}\n\n"
@@ -475,7 +474,6 @@ class RestFormat(OutputFormat):
def out_typedef(self, fname, name, args):
oldprefix = self.lineprefix
- name = args.get('typedef', '')
ln = args.get('declaration_start_line', 0)
self.data += f"\n\n.. c:type:: {name}\n\n"
@@ -492,7 +490,6 @@ class RestFormat(OutputFormat):
def out_struct(self, fname, name, args):
- name = args.get('struct', "")
purpose = args.get('purpose', "")
declaration = args.get('definition', "")
dtype = args.get('type', "struct")
@@ -632,16 +629,16 @@ class ManFormat(OutputFormat):
def out_function(self, fname, name, args):
"""output function in man"""
- self.data += f'.TH "{args["function"]}" 9 "{args["function"]}" "{self.man_date}" "Kernel Hacker\'s Manual" LINUX' + "\n"
+ self.data += f'.TH "{name}" 9 "{name}" "{self.man_date}" "Kernel Hacker\'s Manual" LINUX' + "\n"
self.data += ".SH NAME\n"
- self.data += f"{args['function']} \\- {args['purpose']}\n"
+ self.data += f"{name} \\- {args['purpose']}\n"
self.data += ".SH SYNOPSIS\n"
if args.get('functiontype', ''):
- self.data += f'.B "{args["functiontype"]}" {args["function"]}' + "\n"
+ self.data += f'.B "{args["functiontype"]}" {name}' + "\n"
else:
- self.data += f'.B "{args["function"]}' + "\n"
+ self.data += f'.B "{name}' + "\n"
count = 0
parenth = "("
@@ -676,16 +673,13 @@ class ManFormat(OutputFormat):
self.output_highlight(text)
def out_enum(self, fname, name, args):
-
- name = args.get('enum', '')
-
- self.data += f'.TH "{self.modulename}" 9 "enum {args["enum"]}" "{self.man_date}" "API Manual" LINUX' + "\n"
+ self.data += f'.TH "{self.modulename}" 9 "enum {name}" "{self.man_date}" "API Manual" LINUX' + "\n"
self.data += ".SH NAME\n"
- self.data += f"enum {args['enum']} \\- {args['purpose']}\n"
+ self.data += f"enum {name} \\- {args['purpose']}\n"
self.data += ".SH SYNOPSIS\n"
- self.data += f"enum {args['enum']}" + " {\n"
+ self.data += f"enum {name}" + " {\n"
count = 0
for parameter in args.parameterlist:
@@ -710,13 +704,12 @@ class ManFormat(OutputFormat):
def out_typedef(self, fname, name, args):
module = self.modulename
- typedef = args.get('typedef')
purpose = args.get('purpose')
- self.data += f'.TH "{module}" 9 "{typedef}" "{self.man_date}" "API Manual" LINUX' + "\n"
+ self.data += f'.TH "{module}" 9 "{name}" "{self.man_date}" "API Manual" LINUX' + "\n"
self.data += ".SH NAME\n"
- self.data += f"typedef {typedef} \\- {purpose}\n"
+ self.data += f"typedef {name} \\- {purpose}\n"
for section, text in args.sections.items():
self.data += f'.SH "{section}"' + "\n"
@@ -724,22 +717,20 @@ class ManFormat(OutputFormat):
def out_struct(self, fname, name, args):
module = self.modulename
- struct_type = args.get('type')
- struct_name = args.get('struct')
purpose = args.get('purpose')
definition = args.get('definition')
- self.data += f'.TH "{module}" 9 "{struct_type} {struct_name}" "{self.man_date}" "API Manual" LINUX' + "\n"
+ self.data += f'.TH "{module}" 9 "{args.type} {name}" "{self.man_date}" "API Manual" LINUX' + "\n"
self.data += ".SH NAME\n"
- self.data += f"{struct_type} {struct_name} \\- {purpose}\n"
+ self.data += f"{args.type} {name} \\- {purpose}\n"
# Replace tabs with two spaces and handle newlines
declaration = definition.replace("\t", " ")
declaration = KernRe(r"\n").sub('"\n.br\n.BI "', declaration)
self.data += ".SH SYNOPSIS\n"
- self.data += f"{struct_type} {struct_name} " + "{" + "\n.br\n"
+ self.data += f"{args.type} {name} " + "{" + "\n.br\n"
self.data += f'.BI "{declaration}\n' + "};\n.br\n\n"
self.data += ".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 += 1
self.output_declaration(decl_type, declaration_name,
- struct=declaration_name,
definition=declaration,
purpose=self.entry.declaration_purpose)
@@ -870,7 +869,6 @@ class KernelDoc:
f"Excess enum value '%{k}' description in '{declaration_name}'")
self.output_declaration('enum', declaration_name,
- enum=declaration_name,
purpose=self.entry.declaration_purpose)
def dump_declaration(self, ln, prototype):
@@ -1031,14 +1029,12 @@ class KernelDoc:
if 'typedef' in return_type:
self.output_declaration(decl_type, declaration_name,
- function=declaration_name,
typedef=True,
functiontype=return_type,
purpose=self.entry.declaration_purpose,
func_macro=func_macro)
else:
self.output_declaration(decl_type, declaration_name,
- function=declaration_name,
typedef=False,
functiontype=return_type,
purpose=self.entry.declaration_purpose,
@@ -1077,7 +1073,6 @@ class KernelDoc:
self.create_parameter_list(ln, decl_type, args, ',', declaration_name)
self.output_declaration(decl_type, declaration_name,
- function=declaration_name,
typedef=True,
functiontype=return_type,
purpose=self.entry.declaration_purpose)
@@ -1099,7 +1094,6 @@ class KernelDoc:
return
self.output_declaration('typedef', declaration_name,
- typedef=declaration_name,
purpose=self.entry.declaration_purpose)
return
--
2.49.0
^ permalink raw reply related [flat|nested] 21+ messages in thread* [PATCH v2 09/12] docs: kdoc: straighten up dump_declaration()
2025-07-10 23:31 [PATCH v2 00/12] Thrash up the parser/output interface Jonathan Corbet
` (7 preceding siblings ...)
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 ` Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 10/12] docs: kdoc: directly access the always-there KdocItem fields Jonathan Corbet
` (3 subsequent siblings)
12 siblings, 0 replies; 21+ messages in thread
From: Jonathan Corbet @ 2025-07-10 23:31 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa,
Jonathan Corbet
Get rid of the excess "return" statements in dump_declaration(), along with
a line of never-executed dead code.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
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:
if self.entry.decl_type == "enum":
self.dump_enum(ln, prototype)
- return
-
- if self.entry.decl_type == "typedef":
+ elif self.entry.decl_type == "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=self.entry)
+ else:
+ # This would be a bug
+ self.emit_message(ln, f'Unknown declaration type: {self.entry.decl_type}')
def dump_function(self, ln, prototype):
"""
--
2.49.0
^ permalink raw reply related [flat|nested] 21+ messages in thread* [PATCH v2 10/12] docs: kdoc: directly access the always-there KdocItem fields
2025-07-10 23:31 [PATCH v2 00/12] Thrash up the parser/output interface Jonathan Corbet
` (8 preceding siblings ...)
2025-07-10 23:31 ` [PATCH v2 09/12] docs: kdoc: straighten up dump_declaration() Jonathan Corbet
@ 2025-07-10 23:31 ` Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 11/12] docs: kdoc: clean up check_sections() Jonathan Corbet
` (2 subsequent siblings)
12 siblings, 0 replies; 21+ messages in thread
From: Jonathan Corbet @ 2025-07-10 23:31 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa,
Jonathan Corbet
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 <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
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 = other_stuff
def get(self, key, default = None):
- ret = self.other_stuff.get(key, default)
- if ret == default:
- return self.__dict__.get(key, default)
- return ret
+ return self.other_stuff.get(key, default)
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.
"""
- warnings = args.get('warnings', [])
-
- for log_msg in warnings:
+ for log_msg in args.warnings:
self.config.warning(log_msg)
def check_doc(self, name, args):
@@ -184,7 +182,7 @@ class OutputFormat:
self.data = ""
- dtype = args.get('type', "")
+ dtype = args.type
if dtype == "doc":
self.out_doc(fname, name, args)
@@ -373,7 +371,7 @@ class RestFormat(OutputFormat):
signature = args['functiontype'] + " "
signature += name + " ("
- ln = args.get('declaration_start_line', 0)
+ ln = args.declaration_start_line
count = 0
for parameter in args.parameterlist:
if count != 0:
@@ -445,7 +443,7 @@ class RestFormat(OutputFormat):
def out_enum(self, fname, name, args):
oldprefix = self.lineprefix
- ln = args.get('declaration_start_line', 0)
+ ln = args.declaration_start_line
self.data += f"\n\n.. c:enum:: {name}\n\n"
@@ -474,7 +472,7 @@ class RestFormat(OutputFormat):
def out_typedef(self, fname, name, args):
oldprefix = self.lineprefix
- ln = args.get('declaration_start_line', 0)
+ ln = args.declaration_start_line
self.data += f"\n\n.. c:type:: {name}\n\n"
@@ -492,8 +490,8 @@ class RestFormat(OutputFormat):
purpose = args.get('purpose', "")
declaration = args.get('definition', "")
- dtype = args.get('type', "struct")
- ln = args.get('declaration_start_line', 0)
+ dtype = args.type
+ ln = args.declaration_start_line
self.data += f"\n\n.. c:{dtype}:: {name}\n\n"
--
2.49.0
^ permalink raw reply related [flat|nested] 21+ messages in thread* [PATCH v2 11/12] docs: kdoc: clean up check_sections()
2025-07-10 23:31 [PATCH v2 00/12] Thrash up the parser/output interface Jonathan Corbet
` (9 preceding siblings ...)
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 ` 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 4:29 ` [PATCH v2 00/12] Thrash up the parser/output interface Akira Yokosawa
12 siblings, 0 replies; 21+ messages in thread
From: Jonathan Corbet @ 2025-07-10 23:31 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa,
Jonathan Corbet
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 <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
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 = doc_com + KernRe(r'(\w+)', cache=False)
# @{section-name}:
# while trying to not match literal block starts like "example::"
#
+known_section_names = 'description|context|returns?|notes?|examples?'
+known_sections = KernRe(known_section_names, flags = re.I)
doc_sect = doc_com + \
- KernRe(r'\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:([^:].*)?$',
- flags=re.I, cache=False)
+ KernRe(r'\s*(\@[.\w]+|\@\.\.\.|' + known_section_names + r')\s*:([^:].*)?$',
+ flags=re.I, cache=False)
doc_content = doc_com_body + KernRe(r'(.*)', cache=False)
doc_inline_start = KernRe(r'^\s*/\*\*\s*$', cache=False)
@@ -115,7 +117,6 @@ class KernelEntry:
self.config = config
self._contents = []
- self.sectcheck = ""
self.prototype = ""
self.warnings = []
@@ -187,7 +188,6 @@ class KernelEntry:
self.parameterdescs[name] = contents
self.parameterdesc_start_lines[name] = self.new_start_line
- self.sectcheck += name + " "
self.new_start_line = 0
else:
@@ -478,29 +478,20 @@ class KernelDoc:
self.push_parameter(ln, decl_type, param, dtype,
arg, declaration_name)
- 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 = sectcheck.split()
-
- for sx in range(len(sects)): # pylint: disable=C0200
- err = True
- for param in self.entry.parameterlist:
- if param == sects[sx]:
- err = 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 == 'function':
dname = f"{decl_type} parameter"
else:
dname = f"{decl_type} member"
-
self.emit_msg(ln,
- f"Excess {dname} '{sects[sx]}' description in '{decl_name}'")
+ f"Excess {dname} '{section}' description in '{decl_name}'")
def check_return_section(self, ln, declaration_name, return_type):
"""
@@ -754,7 +745,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.check_sections(ln, declaration_name, decl_type)
# Adjust declaration for better display
declaration = 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
- self.check_sections(ln, declaration_name, "function", self.entry.sectcheck)
+ self.check_sections(ln, declaration_name, "function")
self.check_return_section(ln, declaration_name, return_type)
--
2.49.0
^ permalink raw reply related [flat|nested] 21+ messages in thread* [PATCH v2 12/12] docs: kdoc: emit a warning for ancient versions of Python
2025-07-10 23:31 [PATCH v2 00/12] Thrash up the parser/output interface Jonathan Corbet
` (10 preceding siblings ...)
2025-07-10 23:31 ` [PATCH v2 11/12] docs: kdoc: clean up check_sections() Jonathan Corbet
@ 2025-07-10 23:31 ` 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
12 siblings, 1 reply; 21+ messages in thread
From: Jonathan Corbet @ 2025-07-10 23:31 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa,
Jonathan Corbet
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 <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
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 embedded
documentation comments
"""
+import sys
import re
from pprint import pformat
@@ -238,6 +239,14 @@ class KernelDoc:
# Place all potential outputs into an array
self.entries = []
+ #
+ # We need Python 3.7 for its "dicts remember the insertion
+ # order" guarantee
+ #
+ if sys.version_info.major == 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=True):
"""Emit a message"""
--
2.49.0
^ permalink raw reply related [flat|nested] 21+ messages in thread* Re: [PATCH v2 12/12] docs: kdoc: emit a warning for ancient versions of Python
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
0 siblings, 0 replies; 21+ messages in thread
From: Mauro Carvalho Chehab @ 2025-07-11 5:49 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Akira Yokosawa
Em Thu, 10 Jul 2025 17:31:42 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> 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 <mchehab+huawei@kernel.org>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
> 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 embedded
> documentation comments
> """
>
> +import sys
> import re
> from pprint import pformat
>
> @@ -238,6 +239,14 @@ class KernelDoc:
> # Place all potential outputs into an array
> self.entries = []
>
> + #
> + # We need Python 3.7 for its "dicts remember the insertion
> + # order" guarantee
> + #
> + if sys.version_info.major == 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=True):
> """Emit a message"""
>
Thanks,
Mauro
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH v2 00/12] Thrash up the parser/output interface
2025-07-10 23:31 [PATCH v2 00/12] Thrash up the parser/output interface Jonathan Corbet
` (11 preceding siblings ...)
2025-07-10 23:31 ` [PATCH v2 12/12] docs: kdoc: emit a warning for ancient versions of Python Jonathan Corbet
@ 2025-07-11 4:29 ` Akira Yokosawa
2025-07-11 7:29 ` Mauro Carvalho Chehab
2025-07-11 13:17 ` Jonathan Corbet
12 siblings, 2 replies; 21+ messages in thread
From: Akira Yokosawa @ 2025-07-11 4:29 UTC (permalink / raw)
To: Jonathan Corbet, linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa
On Thu, 10 Jul 2025 17:31:30 -0600, Jonathan Corbet wrote:
[...]
> Changes since v1:
> - Coding-style tweaks requested by Mauro
> - Drop the reworking of output-text accumulation for now
> - Add a warning for prehistoric Python versions
Serious review of python code is beyond my background, but I did a test
on this against opensuse/leap:15.6's python3-Sphinx_4_2_0, which comes with
python 3.6.15.
Running "./scripts/kernel-doc.py -none include/linux/rcupdate.h" emits this:
------------------------------------------------------------------------
Traceback (most recent call last):
File "./scripts/kernel-doc.py", line 315, in <module>
main()
File "./scripts/kernel-doc.py", line 286, in main
kfiles.parse(args.files, export_file=args.export_file)
File "/linux/scripts/lib/kdoc/kdoc_files.py", line 222, in parse
self.parse_file(fname)
File "/linux/scripts/lib/kdoc/kdoc_files.py", line 119, in parse_file
doc = KernelDoc(self.config, fname)
File "/linux/scripts/lib/kdoc/kdoc_parser.py", line 247, in __init__
self.emit_message(0,
AttributeError: 'KernelDoc' object has no attribute 'emit_message'
------------------------------------------------------------------------
This error appeared in 12/12. No errors with python3 >=3.9.
I'm not sure but asking compatibility with python <3.9 increases
maintainers/testers' burden. Obsoleting <3.9 all together would
make everyone's life easier, wouldn't it?
Thanks, Akira
^ permalink raw reply [flat|nested] 21+ messages in thread* Re: [PATCH v2 00/12] Thrash up the parser/output interface
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
1 sibling, 0 replies; 21+ messages in thread
From: Mauro Carvalho Chehab @ 2025-07-11 7:29 UTC (permalink / raw)
To: Akira Yokosawa; +Cc: Jonathan Corbet, linux-doc, linux-kernel
Em Fri, 11 Jul 2025 13:29:00 +0900
Akira Yokosawa <akiyks@gmail.com> escreveu:
> On Thu, 10 Jul 2025 17:31:30 -0600, Jonathan Corbet wrote:
> [...]
>
> > Changes since v1:
> > - Coding-style tweaks requested by Mauro
> > - Drop the reworking of output-text accumulation for now
> > - Add a warning for prehistoric Python versions
>
> Serious review of python code is beyond my background, but I did a test
> on this against opensuse/leap:15.6's python3-Sphinx_4_2_0, which comes with
> python 3.6.15.
>
> Running "./scripts/kernel-doc.py -none include/linux/rcupdate.h" emits this:
>
> ------------------------------------------------------------------------
> Traceback (most recent call last):
> File "./scripts/kernel-doc.py", line 315, in <module>
> main()
> File "./scripts/kernel-doc.py", line 286, in main
> kfiles.parse(args.files, export_file=args.export_file)
> File "/linux/scripts/lib/kdoc/kdoc_files.py", line 222, in parse
> self.parse_file(fname)
> File "/linux/scripts/lib/kdoc/kdoc_files.py", line 119, in parse_file
> doc = KernelDoc(self.config, fname)
> File "/linux/scripts/lib/kdoc/kdoc_parser.py", line 247, in __init__
> self.emit_message(0,
> AttributeError: 'KernelDoc' object has no attribute 'emit_message'
> ------------------------------------------------------------------------
>
> This error appeared in 12/12. No errors with python3 >=3.9.
This is actually a bug. See:
+ #
+ # We need Python 3.7 for its "dicts remember the insertion
+ # order" guarantee
+ #
+ if sys.version_info.major == 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=True):
"""Emit a message"""
The answer is just below the modified code: the function name is actually:
self.emit_msg()
> I'm not sure but asking compatibility with python <3.9 increases
> maintainers/testers' burden. Obsoleting <3.9 all together would
> make everyone's life easier, wouldn't it?
I'd say that the best is to have:
scripts/sphinx-pre-install:
- be compatible with Python 3.6, as it is needed to detect and
request Python upgrades where needed.
- For the doc build, based on my tests with the pre-install tool,
all distros on my testlist have at least Python >= 3.9 as optional
packages.
Now, kernel-doc is a special case, as it is called during Kernel
builds, with "-none". In the specific case of this patchset, running
Python 3.6 would randomize the order of struct and function arguments.
Not a problem when "-none" is used. So, compilation should not
break.
Shifting kernel-doc minimal version to Python >= 3.9, will
require an extra logic at kerneldoc to abort early if "-none"
is used with too old Python, as otherwise it will break kernel
builds for RHEL8, OpenSUSE Leap, OpenMandriva Lx 4.3 and to
other distros (those three comes with 3.6).
Jon,
I sent a two-patches series addressing such issues with kernel-doc
exec file.
I would keep patch 12/12, fixing it from:
self.emit_message -> self.emit_msg
as the warning is emitted when using kdoc classes, which is now the
default.
-
Btw, if you use Fedora, you can easily install python 3.6 there via
dnf:
$ dnf search python 3.6
Updating and loading repositories:
Repositories loaded.
Matched fields: name, summary
python3.6.i686: Version 3.6 of the Python interpreter
python3.6.x86_64: Version 3.6 of the Python interpreter
(Fedora 42 also have all python versions from 3.9 to 3.14 beta also
via dnf)
Regards,
Mauro
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [PATCH v2 00/12] Thrash up the parser/output interface
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
1 sibling, 0 replies; 21+ messages in thread
From: Jonathan Corbet @ 2025-07-11 13:17 UTC (permalink / raw)
To: Akira Yokosawa, linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa
Akira Yokosawa <akiyks@gmail.com> writes:
> On Thu, 10 Jul 2025 17:31:30 -0600, Jonathan Corbet wrote:
> [...]
>
>> Changes since v1:
>> - Coding-style tweaks requested by Mauro
>> - Drop the reworking of output-text accumulation for now
>> - Add a warning for prehistoric Python versions
>
> Serious review of python code is beyond my background, but I did a test
> on this against opensuse/leap:15.6's python3-Sphinx_4_2_0, which comes with
> python 3.6.15.
>
> Running "./scripts/kernel-doc.py -none include/linux/rcupdate.h" emits this:
>
> ------------------------------------------------------------------------
> Traceback (most recent call last):
> File "./scripts/kernel-doc.py", line 315, in <module>
> main()
> File "./scripts/kernel-doc.py", line 286, in main
> kfiles.parse(args.files, export_file=args.export_file)
> File "/linux/scripts/lib/kdoc/kdoc_files.py", line 222, in parse
> self.parse_file(fname)
> File "/linux/scripts/lib/kdoc/kdoc_files.py", line 119, in parse_file
> doc = KernelDoc(self.config, fname)
> File "/linux/scripts/lib/kdoc/kdoc_parser.py", line 247, in __init__
> self.emit_message(0,
> AttributeError: 'KernelDoc' object has no attribute 'emit_message'
> ------------------------------------------------------------------------
>
> This error appeared in 12/12. No errors with python3 >=3.9.
Well, it does make it clear that things won't work properly with older
Python... :)
Seriously, though, that's embarrassing; I was clearly in too much of a
hurry when I tossed that last patch in. Will fix.
> I'm not sure but asking compatibility with python <3.9 increases
> maintainers/testers' burden. Obsoleting <3.9 all together would
> make everyone's life easier, wouldn't it?
That is pretty much what we have done, this was just intended to let
people know that they won't get the results they expect.
Thanks,
jon
^ permalink raw reply [flat|nested] 21+ messages in thread