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 08/12] docs: kdoc: Regularize the use of the declaration name
Date: Thu, 10 Jul 2025 08:22:01 +0200 [thread overview]
Message-ID: <20250710082201.3a4aa762@foz.lan> (raw)
In-Reply-To: <20250702223524.231794-9-corbet@lwn.net>
Em Wed, 2 Jul 2025 16:35:20 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> Each declaration type passes through the name in a unique field of the
> "args" blob - even though we have always just passed the name separately.
> Get rid of all the weird names and just use the common version.
>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
LGTM.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
> 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
>
Thanks,
Mauro
next prev parent reply other threads:[~2025-07-10 6:22 UTC|newest]
Thread overview: 41+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-07-02 22:35 [PATCH 00/12] [PATCH 00/11] Thrash up the parser/output interface Jonathan Corbet
2025-07-02 22:35 ` [PATCH 01/12] docs: kdoc; Add a rudimentary class to represent output items Jonathan Corbet
2025-07-10 5:28 ` Mauro Carvalho Chehab
2025-07-02 22:35 ` [PATCH 02/12] docs: kdoc: simplify the output-item passing Jonathan Corbet
2025-07-10 5:29 ` Mauro Carvalho Chehab
2025-07-02 22:35 ` [PATCH 03/12] docs: kdoc: drop "sectionlist" Jonathan Corbet
2025-07-09 16:27 ` Mauro Carvalho Chehab
2025-07-02 22:35 ` [PATCH 04/12] docs: kdoc: Centralize handling of the item section list Jonathan Corbet
2025-07-10 5:45 ` Mauro Carvalho Chehab
2025-07-10 13:25 ` Jonathan Corbet
2025-07-02 22:35 ` [PATCH 05/12] docs: kdoc: remove the "struct_actual" machinery Jonathan Corbet
2025-07-10 6:11 ` Mauro Carvalho Chehab
2025-07-02 22:35 ` [PATCH 06/12] docs: kdoc: use self.entry.parameterlist directly in check_sections() Jonathan Corbet
2025-07-10 6:12 ` Mauro Carvalho Chehab
2025-07-02 22:35 ` [PATCH 07/12] docs: kdoc: Coalesce parameter-list handling Jonathan Corbet
2025-07-10 6:20 ` Mauro Carvalho Chehab
2025-07-02 22:35 ` [PATCH 08/12] docs: kdoc: Regularize the use of the declaration name Jonathan Corbet
2025-07-10 6:22 ` Mauro Carvalho Chehab [this message]
2025-07-02 22:35 ` [PATCH 09/12] docs: kdoc: straighten up dump_declaration() Jonathan Corbet
2025-07-10 6:25 ` Mauro Carvalho Chehab
2025-07-10 13:27 ` Jonathan Corbet
2025-07-10 22:13 ` Mauro Carvalho Chehab
2025-07-02 22:35 ` [PATCH 10/12] docs: kdoc: directly access the always-there KdocItem fields Jonathan Corbet
2025-07-10 6:27 ` Mauro Carvalho Chehab
2025-07-02 22:35 ` [PATCH 11/12] docs: kdoc: clean up check_sections() Jonathan Corbet
2025-07-10 6:29 ` Mauro Carvalho Chehab
2025-07-02 22:35 ` [PATCH 12/12] docs: kdoc: Improve the output text accumulation Jonathan Corbet
2025-07-10 6:41 ` Mauro Carvalho Chehab
2025-07-10 7:13 ` Mauro Carvalho Chehab
2025-07-10 8:19 ` Mauro Carvalho Chehab
2025-07-10 10:10 ` Mauro Carvalho Chehab
2025-07-10 10:31 ` Mauro Carvalho Chehab
2025-07-10 10:59 ` Mauro Carvalho Chehab
2025-07-10 23:30 ` Jonathan Corbet
2025-07-11 6:14 ` Mauro Carvalho Chehab
2025-07-11 12:49 ` Jonathan Corbet
2025-07-11 16:28 ` Mauro Carvalho Chehab
2025-07-11 16:39 ` Jonathan Corbet
2025-07-03 2:07 ` [PATCH 00/12] [PATCH 00/11] Thrash up the parser/output interface Yanteng Si
2025-07-09 15:29 ` Jonathan Corbet
2025-07-09 16:21 ` Mauro Carvalho Chehab
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=20250710082201.3a4aa762@foz.lan \
--to=mchehab+huawei@kernel.org \
--cc=akiyks@gmail.com \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).