[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <20250801080943.63c64bc8@foz.lan>
Date: Fri, 1 Aug 2025 08:09:43 +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 11/12] docs: kdoc: extract output formatting from
dump_struct()
Em Thu, 31 Jul 2025 18:13:25 -0600
Jonathan Corbet <corbet@....net> escreveu:
> The last thing done in dump_struct() is to format the structure for
> printing. That, too, is a separate activity; split it out into its own
> function.
>
> dump_struct() now fits in a single, full-hight editor screen.
>
> Signed-off-by: Jonathan Corbet <corbet@....net>
Splitting it on a separate function LGTM.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
> ---
> scripts/lib/kdoc/kdoc_parser.py | 72 +++++++++++++++++----------------
> 1 file changed, 37 insertions(+), 35 deletions(-)
>
> diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
> index 2b7d7e646367..131956d89f84 100644
> --- a/scripts/lib/kdoc/kdoc_parser.py
> +++ b/scripts/lib/kdoc/kdoc_parser.py
> @@ -738,6 +738,42 @@ class KernelDoc:
> tuples = struct_members.findall(members)
> return members
>
> + #
> + # Format the struct declaration into a standard form for inclusion in the
> + # resulting docs.
> + #
> + def format_struct_decl(self, declaration):
> + #
> + # Insert newlines, get rid of extra spaces.
> + #
> + declaration = KernRe(r'([{;])').sub(r'\1\n', declaration)
> + declaration = KernRe(r'\}\s+;').sub('};', declaration)
> + #
> + # Format inline enums with each member on its own line.
> + #
> + r = KernRe(r'(enum\s+\{[^}]+),([^\n])')
> + while r.search(declaration):
> + declaration = r.sub(r'\1,\n\2', declaration)
> + #
> + # Now go through and supply the right number of tabs
> + # for each line.
> + #
> + def_args = declaration.split('\n')
> + level = 1
> + declaration = ""
> + for clause in def_args:
> + clause = KernRe(r'\s+').sub(' ', clause.strip(), count=1)
> + if clause:
> + if '}' in clause and level > 1:
> + level -= 1
> + if not clause.startswith('#'):
> + declaration += "\t" * level
> + declaration += "\t" + clause + "\n"
> + if "{" in clause and "}" not in clause:
> + level += 1
> + return declaration
> +
> +
> def dump_struct(self, ln, proto):
> """
> Store an entry for an struct or union
> @@ -776,42 +812,8 @@ class KernelDoc:
> self.create_parameter_list(ln, decl_type, members, ';',
> declaration_name)
> self.check_sections(ln, declaration_name, decl_type)
> -
> - # Adjust declaration for better display
> - declaration = KernRe(r'([{;])').sub(r'\1\n', declaration)
> - declaration = KernRe(r'\}\s+;').sub('};', declaration)
> -
> - # Better handle inlined enums
> - while True:
> - r = KernRe(r'(enum\s+\{[^}]+),([^\n])')
> - if not r.search(declaration):
> - break
> -
> - declaration = r.sub(r'\1,\n\2', declaration)
> -
> - def_args = declaration.split('\n')
> - level = 1
> - declaration = ""
> - for clause in def_args:
> -
> - clause = clause.strip()
> - clause = KernRe(r'\s+').sub(' ', clause, count=1)
> -
> - if not clause:
> - continue
> -
> - if '}' in clause and level > 1:
> - level -= 1
> -
> - if not KernRe(r'^\s*#').match(clause):
> - declaration += "\t" * level
> -
> - declaration += "\t" + clause + "\n"
> - if "{" in clause and "}" not in clause:
> - level += 1
> -
> self.output_declaration(decl_type, declaration_name,
> - definition=declaration,
> + definition=self.format_struct_decl(declaration),
> purpose=self.entry.declaration_purpose)
>
> def dump_enum(self, ln, proto):
Thanks,
Mauro
Powered by blists - more mailing lists