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

[Knop, Ryszard]

On Tue, 2026-07-14 at 14:44 -0700, Randy Dunlap wrote:
> Hi,
> 
> 
> On 7/14/26 4:12 AM, Ryszard Knop 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.
> > 
> 
> Seems to work for me.
> 
> > 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..3f88095eab06 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)}')"
> > +
> >      def check_sections(self, ln, decl_name, decl_type):
> >          """
> >          Check for errors inside sections, emitting warnings if not found
> > @@ -566,12 +573,13 @@ class KernelDoc:
> >          for section in self.entry.sections:
> >              if section not in self.entry.parameterlist and \
> >                 not known_sections.search(section):
> > +                hint = self.get_suggestions_hint(section, self.entry.parameterlist)
> >                  if decl_type == 'function':
> >                      dname = f"{decl_type} parameter"
> >                  else:
> >                      dname = f"{decl_type} member"
> >                  self.emit_msg(ln,
> > -                              f"Excess {dname} '{section}' description in '{decl_name}'")
> > +                              f"Excess {dname} '{section}' description in '{decl_name}' {hint}")
> 
> When 'hint' is empty, this statement and/or the similar one below
> adds a trailing space to each of those lines.
> Can you prevent that?  (yeah, it's just a nit)

Sure thing, submitted a v2.

> 
> >  
> >          #
> >          # Check that documented parameter names (from doc comments, including
> > @@ -591,12 +599,13 @@ class KernelDoc:
> >              if param_name in self.entry.parameterlist:
> >                  continue
> >  
> > +            hint = self.get_suggestions_hint(param_name, self.entry.parameterlist)
> >              if decl_type == 'function':
> >                  dname = f"{decl_type} parameter"
> >              else:
> >                  dname = f"{decl_type} member"
> >              self.emit_msg(ln,
> > -                          f"Excess {dname} '{param_name}' description in '{decl_name}'")
> > +                          f"Excess {dname} '{param_name}' description in '{decl_name}' {hint}")
> >  
> >      def check_return_section(self, ln, declaration_name, return_type):
> >          """
> 
> Acked-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
> Tested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
> 
> thanks.
   A. 
Thanks, Ryszard