| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-ID: <20250710082201.3a4aa762@foz.lan>
Date: Thu, 10 Jul 2025 08:22:01 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Jonathan Corbet <corbet@....net>
Cc: linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org, Akira Yokosawa
<akiyks@...il.com>
Subject: Re: [PATCH 08/12] docs: kdoc: Regularize the use of the declaration
name
Em Wed, 2 Jul 2025 16:35:20 -0600
Jonathan Corbet <corbet@....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@....net>
LGTM.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.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
Powered by blists - more mailing lists