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

[Knop, Ryszard]

On Wed, 2026-07-15 at 14:42 +0200, Mauro Carvalho Chehab wrote:
> On Wed, 15 Jul 2026 13:17:26 +0200
> Ryszard Knop <ryszard.knop@xxxxxxxxx> 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@xxxxxxxxx>
> > ---
> >  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.

The checks here specifically were added to deal with situations like
[1] which boils down to:

struct {
    /** @flags: good description */
    int flags;

    /** @substruct: also good */
    struct {
        /** @mode: bad, wrong, no good */
        int mode;
    } substruct;
} big_block_o_data;

The docs should say "@substruct.mode" instead of just "@mode", so this
is distant enough from the actual input that difflib would not suggest
it. I could merge suggestions from both difflib and the plain substring
comparison if you'd like me to?

[1] https://patchwork.freedesktop.org/patch/734307/?series=168905&rev=1

> 
> Regards,
> Mauro

Thanks, Ryszard