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

[Knop, Ryszard]

On Wed, 2026-07-15 at 15:52 +0200, Mauro Carvalho Chehab wrote:
> On Wed, 15 Jul 2026 13:21:27 +0000
> "Knop, Ryszard" <ryszard.knop@xxxxxxxxx> 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@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. 
> 
> 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.

Submitted v3 with slightly more complex suggestions set up like this:

- First, we suggest nested struct names. For "substruct.member", we
compare the kdoc declaration name with "member" after the last dot.
Exact matches go first, then substrings, then the difflib suggestion
(so that 'flgas' still matches 'substruct.flags').
- Then we compare decl name on the full known possible member name,
first with substrings and then with difflib again.
- All that gets deduplicated and merged in the order listed above.

Link to v3:
https://lore.kernel.org/linux-doc/20260717125753.634550-1-ryszard.knop@xxxxxxxxx/

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

Thanks, Ryszard