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

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

[Ryszard Knop]

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.

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..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}")
 
         #
         # 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):
         """
-- 
2.55.0

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

[Randy Dunlap]

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

>  
>          #
>          # 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@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

thanks.
-- 
~Randy

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

[Ryszard Knop]

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)}')"
+
     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}".strip())
 
         #
         # 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}".strip())
 
     def check_return_section(self, ln, declaration_name, return_type):
         """
-- 
2.55.0

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@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..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@infradead.org>
> Tested-by: Randy Dunlap <rdunlap@infradead.org>
> 
> thanks.
   A. 
Thanks, Ryszard

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

[Mauro Carvalho Chehab]

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

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

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

[Mauro Carvalho Chehab]

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

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

[Jonathan Corbet]

Ryszard Knop <ryszard.knop@intel.com> writes:

> 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.
>
> Signed-off-by: Ryszard Knop <ryszard.knop@intel.com>
> ---
>  tools/lib/python/kdoc/kdoc_parser.py | 13 +++++++++++--
>  1 file changed, 11 insertions(+), 2 deletions(-)

So I almost applied this version of this patch.  For future reference,
please:

- Post new versions standalone, not as a reply

- Do not include version information in the changelog (put it below the
  "---" line)

- Provide a more coherent changelog; the one above does not say what is
  actually going on here.

- CC the maintainer (me).

Thanks,

jon

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

[Ryszard Knop]

Recent check_sections() change added a warning if a documentation tag
member name does not match the detected struct/union member names. Since
the checker knows all possible names, we can suggest known names, so
that it's more obvious how to deal with the warning.

Signed-off-by: Ryszard Knop <ryszard.knop@intel.com>
---
Changes in v1:
- Added the suggestion hint in the warning, with basic name substring checks
- Link: https://lore.kernel.org/linux-doc/20260714111208.323108-1-ryszard.knop@intel.com/

Changes in v2:
- Strip trailing whitespace from the warning when the generated hint is empty
- Link: https://lore.kernel.org/linux-doc/20260715111726.394565-1-ryszard.knop@intel.com/

v3:
- Use difflib to generate suggestions even if the tag member is mistyped
- Suggest names based on the nested struct members too
---
 tools/lib/python/kdoc/kdoc_parser.py | 51 ++++++++++++++++++++++++++--
 1 file changed, 49 insertions(+), 2 deletions(-)

diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
index 2dedda215c22..884f42584667 100644
--- a/tools/lib/python/kdoc/kdoc_parser.py
+++ b/tools/lib/python/kdoc/kdoc_parser.py
@@ -11,6 +11,7 @@ and extract embedded documentation comments from it.
 
 import sys
 import re
+import difflib
 from pprint import pformat
 
 from kdoc.c_lex import CTokenizer, tokenizer_set_log
@@ -558,6 +559,50 @@ class KernelDoc:
                         self.push_parameter(ln, decl_type, param, dtype,
                                             arg, declaration_name)
 
+    def get_suggestions_hint(self, decl_name, possible_names):
+        # For decl name 'flags' or 'flgas', suggests 'substruct.flags'
+        submember_exact = []
+        submember_substrings = []
+        submember_suggestions = []
+        for possible_name in possible_names:
+            parts = possible_name.strip().split('.')
+            if len(parts) < 2:
+                continue
+
+            final_part = parts[-1]
+            if decl_name == final_part:
+                submember_exact.append(possible_name)
+            elif decl_name in final_part:
+                submember_substrings.append(possible_name)
+            elif difflib.get_close_matches(decl_name, [final_part]):
+                submember_suggestions.append(possible_name)
+
+        # For decl name 'flgas', suggests 'flags'
+        full_suggestions = difflib.get_close_matches(decl_name, possible_names)
+
+        # For decl name 'member', suggests 'longer_member'
+        full_substrings = [name for name in possible_names if decl_name in name]
+
+        ordered_lists = [
+            submember_exact,
+            submember_substrings,
+            submember_suggestions,
+            full_suggestions,
+            full_substrings,
+        ]
+
+        # Deduplicate but maintain order from most to least likely:
+        unique_suggestions = {}
+        for suggestion_list in ordered_lists:
+            for suggestion in suggestion_list:
+                unique_suggestions[suggestion] = None
+
+        suggestions = list(unique_suggestions.keys())
+        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 +611,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}".strip())
 
         #
         # Check that documented parameter names (from doc comments, including
@@ -591,12 +637,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}".strip())
 
     def check_return_section(self, ln, declaration_name, return_type):
         """
-- 
2.55.0

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

[Knop, Ryszard]

On Thu, 2026-07-16 at 16:40 -0600, Jonathan Corbet wrote:
> Ryszard Knop <ryszard.knop@intel.com> writes:
> 
> > 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.
> > 
> > Signed-off-by: Ryszard Knop <ryszard.knop@intel.com>
> > ---
> >  tools/lib/python/kdoc/kdoc_parser.py | 13 +++++++++++--
> >  1 file changed, 11 insertions(+), 2 deletions(-)
> 
> So I almost applied this version of this patch.  For future reference,
> please:
> 
> - Post new versions standalone, not as a reply
> 
> - Do not include version information in the changelog (put it below the
>   "---" line)
> 
> - Provide a more coherent changelog; the one above does not say what is
>   actually going on here.
> 
> - CC the maintainer (me).

Submitted a v3 with changes Mauro requested, fixed changelog and CC'd,
but accidentally sent it again with In-Reply-To which I had in the
command last time, sorry :/

> 
> Thanks,
> 
> jon

Thanks, Ryszard

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

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@intel.com/

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

Thanks, Ryszard

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

[Randy Dunlap]

On 7/17/26 5:57 AM, Ryszard Knop wrote:
> Recent check_sections() change added a warning if a documentation tag
> member name does not match the detected struct/union member names. Since
> the checker knows all possible names, we can suggest known names, so
> that it's more obvious how to deal with the warning.
> 
> Signed-off-by: Ryszard Knop <ryszard.knop@intel.com>

Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

> ---
> Changes in v1:
> - Added the suggestion hint in the warning, with basic name substring checks
> - Link: https://lore.kernel.org/linux-doc/20260714111208.323108-1-ryszard.knop@intel.com/
> 
> Changes in v2:
> - Strip trailing whitespace from the warning when the generated hint is empty
> - Link: https://lore.kernel.org/linux-doc/20260715111726.394565-1-ryszard.knop@intel.com/
> 
> v3:
> - Use difflib to generate suggestions even if the tag member is mistyped
> - Suggest names based on the nested struct members too
> ---
>  tools/lib/python/kdoc/kdoc_parser.py | 51 ++++++++++++++++++++++++++--
>  1 file changed, 49 insertions(+), 2 deletions(-)
> 
> diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
> index 2dedda215c22..884f42584667 100644
> --- a/tools/lib/python/kdoc/kdoc_parser.py
> +++ b/tools/lib/python/kdoc/kdoc_parser.py
> @@ -11,6 +11,7 @@ and extract embedded documentation comments from it.
>  
>  import sys
>  import re
> +import difflib
>  from pprint import pformat
>  
>  from kdoc.c_lex import CTokenizer, tokenizer_set_log
> @@ -558,6 +559,50 @@ class KernelDoc:
>                          self.push_parameter(ln, decl_type, param, dtype,
>                                              arg, declaration_name)
>  
> +    def get_suggestions_hint(self, decl_name, possible_names):
> +        # For decl name 'flags' or 'flgas', suggests 'substruct.flags'
> +        submember_exact = []
> +        submember_substrings = []
> +        submember_suggestions = []
> +        for possible_name in possible_names:
> +            parts = possible_name.strip().split('.')
> +            if len(parts) < 2:
> +                continue
> +
> +            final_part = parts[-1]
> +            if decl_name == final_part:
> +                submember_exact.append(possible_name)
> +            elif decl_name in final_part:
> +                submember_substrings.append(possible_name)
> +            elif difflib.get_close_matches(decl_name, [final_part]):
> +                submember_suggestions.append(possible_name)
> +
> +        # For decl name 'flgas', suggests 'flags'
> +        full_suggestions = difflib.get_close_matches(decl_name, possible_names)
> +
> +        # For decl name 'member', suggests 'longer_member'
> +        full_substrings = [name for name in possible_names if decl_name in name]
> +
> +        ordered_lists = [
> +            submember_exact,
> +            submember_substrings,
> +            submember_suggestions,
> +            full_suggestions,
> +            full_substrings,
> +        ]
> +
> +        # Deduplicate but maintain order from most to least likely:
> +        unique_suggestions = {}
> +        for suggestion_list in ordered_lists:
> +            for suggestion in suggestion_list:
> +                unique_suggestions[suggestion] = None
> +
> +        suggestions = list(unique_suggestions.keys())
> +        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 +611,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}".strip())
>  
>          #
>          # Check that documented parameter names (from doc comments, including
> @@ -591,12 +637,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}".strip())
>  
>      def check_return_section(self, ln, declaration_name, return_type):
>          """

-- 
~Randy