From b68f29353e5b9b7a9da5fdc5a49e695450ff57c7 Mon Sep 17 00:00:00 2001 From: Yousef Alhouseen Date: Wed, 24 Jun 2026 14:24:48 +0200 Subject: docs: kdoc: fix troff output description typo Fix a typo in the ManFormat documentation string that describes the generated troff title header fields. Signed-off-by: Yousef Alhouseen Signed-off-by: Jonathan Corbet Message-ID: <20260624122448.4853-1-alhouseenyousef@gmail.com> --- tools/lib/python/kdoc/kdoc_output.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'tools/lib/python') diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/kdoc_output.py index de107ab4a281..618b0d765ef5 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -624,7 +624,7 @@ class ManFormat(OutputFormat): ``manual`` Defaults to ``Kernel API Manual``. - The above controls the output of teh corresponding fields on troff + The above controls the output of the corresponding fields on troff title headers, which will be filled like this:: .TH "{name}" {section} "{date}" "{modulename}" "{manual}" -- cgit v1.2.3 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') 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') 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') 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 From 7bcc15b25674b7443a69b887e2b223366a3ad26a Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Thu, 23 Jul 2026 12:01:51 -0700 Subject: docs: xforms_lists: support DEFINE_IDTENTRY_IRQ() Avoid kernel-doc warnings by supported DEFINE_IDTENTRY_IRQ() as a function transform. Warning: arch/x86/kernel/apic/apic.c:2157 function parameter 'spurious_interrupt' not described in 'DEFINE_IDTENTRY_IRQ' Warning: arch/x86/kernel/apic/apic.c:2157 expecting prototype for spurious_interrupt(). Prototype was for DEFINE_IDTENTRY_IRQ() instead Signed-off-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20260723190151.507295-1-rdunlap@infradead.org> --- tools/lib/python/kdoc/xforms_lists.py | 1 + 1 file changed, 1 insertion(+) (limited to 'tools/lib/python') diff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/xforms_lists.py index 4251f7c6673a..e3dda2fe8a53 100644 --- a/tools/lib/python/kdoc/xforms_lists.py +++ b/tools/lib/python/kdoc/xforms_lists.py @@ -90,6 +90,7 @@ class CTransforms: (CMatch("__(?:re)?alloc_size"), ""), (CMatch("__diagnose_as"), ""), (CMatch("DECL_BUCKET_PARAMS"), r"\1, \2"), + (CMatch("DEFINE_IDTENTRY_IRQ"), r"static void \1(struct pt_regs *regs, u32 vector)"), (CMatch("__cond_acquires"), ""), (CMatch("__cond_releases"), ""), (CMatch("__acquires"), ""), -- cgit v1.2.3 From 02299dcd203c55d12238c95f1d028f06b90f1c1e Mon Sep 17 00:00:00 2001 From: Alison Schofield Date: Fri, 7 Aug 2026 15:10:03 -0700 Subject: docs: python: abi_regex: catch the right exception for a bad regex While validating recent CXL ABI documentation updates with get_abi.py, the 'undefined' mode was found to abort instead of reporting undocumented ABI entries. Older Python releases raise re.error, while newer releases expose re.PatternError. Catching the compatible re.error exception handles both cases. Use re.error so the scan continues and reports the remaining results. Signed-off-by: Alison Schofield Signed-off-by: Jonathan Corbet Message-ID: <9f6fa7a9aa6ba9a26b484b911976713356b3fd44.1786139549.git.alison.schofield@intel.com> --- tools/lib/python/abi/abi_regex.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'tools/lib/python') diff --git a/tools/lib/python/abi/abi_regex.py b/tools/lib/python/abi/abi_regex.py index d0c5e3ede6b5..69d8507b7382 100644 --- a/tools/lib/python/abi/abi_regex.py +++ b/tools/lib/python/abi/abi_regex.py @@ -155,7 +155,7 @@ class AbiRegex(AbiParser): if self.search_string: if what.find(self.search_string) >= 0: print(f"What: {what}") - except re.PatternError: + except re.error: self.log.warning("Ignoring '%s' as it produced an invalid regex:\n" " '%s'", what, new) @@ -194,7 +194,7 @@ class AbiRegex(AbiParser): try: self.re_string = re.compile(self.search_string) - except re.PatternError as e: + except re.error as e: msg = f"{self.search_string} is not a valid regular expression" raise ValueError(msg) from e @@ -223,9 +223,9 @@ class AbiRegex(AbiParser): for r, s in self.re_whats: try: new = r.sub(s, new) - except re.PatternError as e: + except re.error as e: # Help debugging troubles with new regexes - raise re.PatternError(f"{e}\nwhile re.sub('{r.pattern}', {s}, str)") from e + raise re.error(f"{e}\nwhile re.sub('{r.pattern}', {s}, str)") from e v["regex"].append(new) -- cgit v1.2.3 From 47646ce123fbd07d7c4d8052831c35f58ffcd074 Mon Sep 17 00:00:00 2001 From: Alison Schofield Date: Fri, 7 Aug 2026 15:10:04 -0700 Subject: docs: python: abi_regex: convert adjacent index placeholders While validating recent CXL ABI documentation updates with get_abi.py, every decoderX.Y entry was reported as undocumented. The placeholder conversion mishandles adjacent index placeholders, producing patterns that cannot match the corresponding sysfs paths. As a result, valid ABI entries are reported as undocumented. Handle adjacent placeholders independently so generated patterns match the documented paths. This fixes decoderX.Y entries in the CXL ABI and other ABI documentation that uses the same naming convention. Signed-off-by: Alison Schofield Signed-off-by: Jonathan Corbet Message-ID: --- tools/lib/python/abi/abi_regex.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'tools/lib/python') diff --git a/tools/lib/python/abi/abi_regex.py b/tools/lib/python/abi/abi_regex.py index 69d8507b7382..198ecbf49c51 100644 --- a/tools/lib/python/abi/abi_regex.py +++ b/tools/lib/python/abi/abi_regex.py @@ -65,8 +65,7 @@ class AbiRegex(AbiParser): (re.compile(r"\[[^\]]+\]"), "\\\\w\xf7"), (re.compile(r"XX+"), "\\\\w\xf7"), - (re.compile(r"([^A-Z])[XYZ]([^A-Z])"), "\\1\\\\w\xf7\\2"), - (re.compile(r"([^A-Z])[XYZ]$"), "\\1\\\\w\xf7"), + (re.compile(r"(?