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

Pull documentation updates from Jonathan Corbet:
 "Things have calmed down a bit on the docs front, with no earthshaking
  changes this time around:

   - Ongoing work on the Japanese and Portuguese translations

   - Better integration of the MAINTAINERS file into the rendered
     documents, including a search interface

   - A seemingly infinite supply of fixes for typos, minor grammatical
     issues, and related problems that LLMs find with abandon"

* tag 'docs-7.2' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux: (93 commits)
  docs: pt_BR: Translate 3.Early-stage.rst into Portuguese
  docs: pt_BR: update "Purpose of Defconfigs" section in maintainer-soc.rst
  Documentation: bug-hunting.rst: fix grammar
  docs/ja_JP: translate submitting-patches.rst (interleaved-replies)
  docs: Fix minor grammatical error
  docs/{it_it,sp_SP,zh_CN,zh_TW}: update references to removed CONFIG_DEBUG_SLAB
  Documentation: process: fix brackets
  Documentation: arch: fix brackets
  docs/dyndbg: explain flags parse 1st
  docs/dyndbg: update examples \012 to \n
  docs: kernel-parameters: Fix stale sticore file paths
  docs: real-time: Fix duplicated sched(7) text
  docs: kgdb: Fix stale source file paths
  docs: sonypi: Fix stale header file path
  docs: kernel-parameters: Remove sa1100ir IrDA parameter
  iommu: Documentation: rearrange, update kernel-parameters
  docs: md: fix grammar in speed_limit description
  docs: changes.rst: restore pahole 1.26 minimum (regressed by sort)
  Documentation: Fix syntax of kmalloc_objs example in coding style doc
  docs: pt_BR: update maintainer-handbooks
  ...

1 files changed, 53 insertions, 1 deletions

diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
index c3f966da533e..2dedda215c22 100644
--- a/tools/lib/python/kdoc/kdoc_parser.py
+++ b/tools/lib/python/kdoc/kdoc_parser.py
@@ -380,9 +380,36 @@ class KernelDoc:
         #
         if dtype == '':
             if param.endswith("..."):
-                if len(param) > 3: # there is a name provided, use that
+                named_variadic = len(param) > 3
+                if named_variadic: # there is a name provided, use that
+                    #
+                    # If the user documented the parameter using the
+                    # ``@name...:`` form, the description is stored in
+                    # parameterdescs under the unstripped key.  Migrate
+                    # it to the stripped key so the user's text is not
+                    # silently dropped during output, and so the new
+                    # excess-parameter check in check_sections() does
+                    # not flag the unstripped key as orphaned.
+                    #
+                    orig = self.entry.parameterdescs.pop(param, None)
                     param = param[:-3]
+                    if orig is not None and \
+                       not self.entry.parameterdescs.get(param):
+                        self.entry.parameterdescs[param] = orig
                 if not self.entry.parameterdescs.get(param):
+                    #
+                    # For a named variadic (e.g. ``args...``), emit the
+                    # standard "not described" warning before auto-filling
+                    # so a missing or mistyped ``@<name>:`` doc tag does
+                    # not go undetected.  The bare ``...`` form has no
+                    # natural name for the user to document and so always
+                    # gets the auto-generated text.
+                    #
+                    if named_variadic and decl_type == 'function':
+                        self.emit_msg(ln,
+                                      f"function parameter '{param}' "
+                                      f"not described in "
+                                      f"'{declaration_name}'")
                     self.entry.parameterdescs[param] = "variable arguments"
 
             elif (not param) or param == "void":
@@ -546,6 +573,31 @@ class KernelDoc:
                 self.emit_msg(ln,
                               f"Excess {dname} '{section}' description in '{decl_name}'")
 
+        #
+        # Check that documented parameter names (from doc comments, including
+        # inline ``/** @member: */`` tags) actually match real members in
+        # the declaration.  This catches mismatched or stale kernel-doc
+        # member tags that don't correspond to any actual struct/union
+        # member or function parameter.
+        #
+        for param_name, desc in self.entry.parameterdescs.items():
+            # Skip auto-generated entries from push_parameter()
+            if desc == self.undescribed:
+                continue
+            if desc in ("no arguments", "anonymous\n", "variable arguments"):
+                continue
+            if param_name.startswith("{unnamed_"):
+                continue
+            if param_name in self.entry.parameterlist:
+                continue
+
+            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}'")
+
     def check_return_section(self, ln, declaration_name, return_type):
         """
         If the function doesn't return void, warns about the lack of a