Re: [PATCH v2] scripts/kernel-doc: Suggest possible names for excess descriptions

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

On Wed, 15 Jul 2026 13:17:26 +0200
Ryszard Knop <ryszard.knop@intel.com> wrote:

> Since check_sections() now warns if a documentation tag member name is
> the same as defined in the struct, we can suggest names the checker
> knows, so that it's more obvious how to deal with the warning.
> 
> v2 (rdunlap):
> - Strip whitespace from warnings, nicer when the hint is empty
> 
> Signed-off-by: Ryszard Knop <ryszard.knop@intel.com>
> ---
>  tools/lib/python/kdoc/kdoc_parser.py | 13 +++++++++++--
>  1 file changed, 11 insertions(+), 2 deletions(-)
> 
> diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
> index 2dedda215c22..a22c3e3182f0 100644
> --- a/tools/lib/python/kdoc/kdoc_parser.py
> +++ b/tools/lib/python/kdoc/kdoc_parser.py
> @@ -558,6 +558,13 @@ class KernelDoc:
>                          self.push_parameter(ln, decl_type, param, dtype,
>                                              arg, declaration_name)
>  
> +    def get_suggestions_hint(self, decl_name, possible_names):
> +        suggestions = set(name for name in possible_names if decl_name in name)
> +        if not suggestions:
> +            return ""
> +
> +        return f"(did you mean one of: '{"', '".join(suggestions)}')"
> +

There is a better way to propose suggestions. See:
	Documentation/sphinx/kernel_include.py

E.g. use something like:

	from difflib import get_close_matches

	matches = get_close_matches(decl_name, possible_names)

See: https://docs.python.org/3/library/difflib.html#difflib.get_close_matches

If the problem is due to a typo, this will likely return the
right name.

Regards,
Mauro