From d7758384ccb470aed7c7a86f0825b1b16bd7a288 Mon Sep 17 00:00:00 2001 From: Ryszard Knop Date: Fri, 17 Jul 2026 14:57:53 +0200 Subject: scripts/kernel-doc: Suggest possible names for excess descriptions 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 Tested-by: Randy Dunlap Acked-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20260717125753.634550-1-ryszard.knop@intel.com> --- tools/lib/python/kdoc/kdoc_parser.py | 51 ++++++++++++++++++++++++++++++++++-- 1 file changed, 49 insertions(+), 2 deletions(-) (limited to 'tools/lib/python/kdoc/kdoc_parser.py') 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): """ -- cgit v1.2.3 From 5ffcd42a9af340764f9bd0ce3f50b156840c196a Mon Sep 17 00:00:00 2001 From: Ryszard Knop Date: Fri, 31 Jul 2026 16:45:08 +0200 Subject: scripts/kernel-doc: Fix kdoc for Python 3.9-3.11 The syntax used by the excess description suggestion change works on Python 3.12+, while we need to support 3.9+. Signed-off-by: Ryszard Knop Tested-by: Akira Yokosawa Fixes: d7758384ccb4 ("scripts/kernel-doc: Suggest possible names for excess descriptions") Reported-by: Akira Yokosawa Closes: https://lore.kernel.org/22a9276d-c103-4306-a617-7f34abcd5c29@gmail.com/ Signed-off-by: Jonathan Corbet Message-ID: <20260731144508.912049-1-ryszard.knop@intel.com> --- tools/lib/python/kdoc/kdoc_parser.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'tools/lib/python/kdoc/kdoc_parser.py') diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py index 884f42584667..9cba20f827c4 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -601,7 +601,8 @@ class KernelDoc: if not suggestions: return "" - return f"(did you mean one of: '{"', '".join(suggestions)}')" + joined_suggestions = "', '".join(suggestions) + return f"(did you mean one of: '{joined_suggestions}')" def check_sections(self, ln, decl_name, decl_type): """ -- cgit v1.2.3 From 3046f4bebd5f322d73afbd1b7fad8ae4ee672284 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Tue, 28 Jul 2026 22:27:36 -0700 Subject: docs: kdoc_parser: drop extraneous blank line in warning message Drop an extra newline (blank line) on warning messages for (2 places): expecting prototype for typedef. Prototype was for typedef {symbol} instead and expecting prototype for {struct|union}. Prototype was for struct|union {symbol} instead This makes these messages consistent with the similar enum warning, which has no extra blank line. Signed-off-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20260729052736.1423688-1-rdunlap@infradead.org> --- tools/lib/python/kdoc/kdoc_parser.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'tools/lib/python/kdoc/kdoc_parser.py') diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py index 9cba20f827c4..d9ad1ddc87dd 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -839,7 +839,7 @@ class KernelDoc: if self.entry.identifier != declaration_name: self.emit_msg(ln, f"expecting prototype for {decl_type} {self.entry.identifier}. " - f"Prototype was for {decl_type} {declaration_name} instead\n") + f"Prototype was for {decl_type} {declaration_name} instead") return # # Go through the list of members applying all of our transformations. @@ -1156,7 +1156,7 @@ class KernelDoc: if self.entry.identifier != declaration_name: self.emit_msg(ln, - f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead\n") + f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead") return self.create_parameter_list(ln, 'function', args, ',', declaration_name) @@ -1176,7 +1176,7 @@ class KernelDoc: if self.entry.identifier != declaration_name: self.emit_msg(ln, - f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead\n") + f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead") return self.output_declaration('typedef', declaration_name, -- cgit v1.2.3