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:21:27 +0000
"Knop, Ryszard" <ryszard.knop@intel.com> wrote:

> 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@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.  
> 
> 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. 

Ok, but there should be cases like, instead of "mode", someone writes
for instance "modes".

> I could merge suggestions from both difflib and the plain substring
> comparison if you'd like me to?

Makes sense to me. Just ensure that they aren't duplicated.

> 
> [1] https://patchwork.freedesktop.org/patch/734307/?series=168905&rev=1
> 
> > 
> > Regards,
> > Mauro  
> 
> Thanks, Ryszard


-- 
Thanks,
Mauro