Merge tag 'docs-7.3' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux

Pull documentation updates from Jonathan Corbet:
 "It has been a not-too-busy cycle for docs; here's the highlights:

   - A (hopefully) consensus change to our LLM-attribution requirements,
     removing the specific model name from the Assisted-by tag

   - A couple of new realtime documents

   - Various docs-build-system fixes

   - Ongoing work with the Chinese, Portuguese, and Japanese
     translations

  ...and lots of typo fixes, grammar tweaks, etc"

* tag 'docs-7.3' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux: (85 commits)
  Doc: admin-guide: pm: Remove unnecessary backticks and fix a spell
  Documentation: Extend the real-time hardware bits with some firmware bits
  docs: pt_BR: Reorganize process/index.rst to follow english structure
  docs: conf.py: fix the 'utf-8' typo
  doc tools: fix 'path' typos
  Documentation: real-time: Add kernel configuration guide
  docs: python: abi_regex: convert adjacent index placeholders
  docs: python: abi_regex: catch the right exception for a bad regex
  docs: sphinx-build-wrapper: include localversion in kernel version string
  Documentation: html: adjust sidebar section titles styling
  Documentation: html: show sections in the sidebar
  checkpatch.pl: adapt to new Assisted-by: format
  MAINTAINERS: update Traditional Chinese documentation maintainers
  docs: pt_BR: process: Translate CVE documentation
  docs: pt_BR: translate the management-style.rst to Brazilian Portuguese
  docs: xforms_lists: support DEFINE_IDTENTRY_IRQ()
  coding-assistants: simplify attribution
  docs: translations: pt_BR: translate email-clients.rst
  docs: pt_BR: process: Translate the security-bugs.rst
  doc:it_IT: align doc-guide translation
  ...

1 files changed, 53 insertions, 5 deletions

diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
index 2dedda215c22..d9ad1ddc87dd 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,51 @@ 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 ""
+
+        joined_suggestions = "', '".join(suggestions)
+        return f"(did you mean one of: '{joined_suggestions}')"
+
     def check_sections(self, ln, decl_name, decl_type):
         """
         Check for errors inside sections, emitting warnings if not found
@@ -566,12 +612,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 +638,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):
         """
@@ -791,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.
@@ -1108,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)
@@ -1128,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,