From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
Akira Yokosawa <akiyks@gmail.com>
Subject: Re: [PATCH v2 07/12] docs: kdoc: Coalesce parameter-list handling
Date: Fri, 11 Jul 2025 07:54:06 +0200 [thread overview]
Message-ID: <20250711075406.76ae06ec@foz.lan> (raw)
In-Reply-To: <20250710233142.246524-8-corbet@lwn.net>
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
next prev parent reply other threads:[~2025-07-11 5:54 UTC|newest]
Thread overview: 21+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-07-10 23:31 [PATCH v2 00/12] Thrash up the parser/output interface Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 01/12] docs: kdoc; Add a rudimentary class to represent output items Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 02/12] docs: kdoc: simplify the output-item passing Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 03/12] docs: kdoc: drop "sectionlist" Jonathan Corbet
2025-07-11 5:50 ` Mauro Carvalho Chehab
2025-07-10 23:31 ` [PATCH v2 04/12] docs: kdoc: Centralize handling of the item section list Jonathan Corbet
2025-07-11 5:52 ` Mauro Carvalho Chehab
2025-07-10 23:31 ` [PATCH v2 05/12] docs: kdoc: remove the "struct_actual" machinery Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 06/12] docs: kdoc: use self.entry.parameterlist directly in check_sections() Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 07/12] docs: kdoc: Coalesce parameter-list handling Jonathan Corbet
2025-07-11 5:54 ` Mauro Carvalho Chehab [this message]
2025-07-11 12:45 ` Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 08/12] docs: kdoc: Regularize the use of the declaration name Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 09/12] docs: kdoc: straighten up dump_declaration() Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 10/12] docs: kdoc: directly access the always-there KdocItem fields Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 11/12] docs: kdoc: clean up check_sections() Jonathan Corbet
2025-07-10 23:31 ` [PATCH v2 12/12] docs: kdoc: emit a warning for ancient versions of Python Jonathan Corbet
2025-07-11 5:49 ` Mauro Carvalho Chehab
2025-07-11 4:29 ` [PATCH v2 00/12] Thrash up the parser/output interface Akira Yokosawa
2025-07-11 7:29 ` Mauro Carvalho Chehab
2025-07-11 13:17 ` Jonathan Corbet
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20250711075406.76ae06ec@foz.lan \
--to=mchehab+huawei@kernel.org \
--cc=akiyks@gmail.com \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
all inboxes | Powered by JetHome®