[PATCH v2] scripts/kernel-doc: Detect mismatched inline member documentation tags

[PATCH v2] scripts/kernel-doc: Detect mismatched inline member documentation tags

[Shuicheng Lin]

Add validation in check_sections() to verify that inline member
documentation tags (/** @member: description */) match actual struct/union
member names. Previously, kernel-doc only validated section headers against
the parameter list, but inline doc tags stored in parameterdescs were never
cross-checked, allowing stale or mistyped member names to go undetected.

The new check iterates over parameterdescs keys and warns about any that
don't appear in the parameter list, catching issues like renamed struct
members where the documentation tag was not updated to match.

This catches real issues such as:
  - xe_bo_types.h: @atomic_access (missing struct prefix, should be
    @attr.atomic_access)
  - xe_device_types.h: @usm.asid (member is actually asid_to_vm)

Variadic arguments documented as ``@args...:`` are stored in
parameterdescs under the unstripped key (e.g. ``args...``), while
push_parameter() strips the trailing ``...`` before appending to
parameterlist (e.g. ``args``).  Treat the stripped form as a match so
the new loop doesn't emit a false-positive excess-parameter warning for
a properly documented named variadic parameter.  The bare ``@...:`` form
is unaffected because push_parameter() does not strip when the name is
exactly three characters.

v2: Skip variadic parameters whose documented key ends with ``...`` and
    whose stripped name is in parameterlist, to avoid false-positive
    "Excess function parameter 'args...'" warnings on macros like
    ``#define foo(fmt, args...)`` documented with ``@args...:``.

Assisted-by: Claude:claude-opus-4.6
Signed-off-by: Shuicheng Lin <shuicheng.lin@intel.com>
---
Cc: Jani Nikula <jani.nikula@linux.intel.com>
Cc: linux-doc@vger.kernel.org
Cc: linux-kernel@vger.kernel.org
Cc: intel-xe@lists.freedesktop.org
---
 tools/lib/python/kdoc/kdoc_parser.py | 36 ++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
index ca00695b47b3..884c6bf56d25 100644
--- a/tools/lib/python/kdoc/kdoc_parser.py
+++ b/tools/lib/python/kdoc/kdoc_parser.py
@@ -673,6 +673,42 @@ 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
+            #
+            # Variadic arguments documented as ``@args...:`` are stored in
+            # parameterdescs under the unstripped key (e.g. ``args...``),
+            # while push_parameter() strips the trailing ``...`` before
+            # appending to parameterlist (e.g. ``args``).  Treat the
+            # stripped form as a match so this loop doesn't emit a false
+            # positive for a properly documented variadic parameter.
+            #
+            if param_name.endswith("...") and \
+               param_name[:-3] 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
-- 
2.43.0

Re: [PATCH v2] scripts/kernel-doc: Detect mismatched inline member documentation tags

[Randy Dunlap]

Hi,

On 5/1/26 9:08 AM, Shuicheng Lin wrote:
> Add validation in check_sections() to verify that inline member
> documentation tags (/** @member: description */) match actual struct/union
> member names. Previously, kernel-doc only validated section headers against
> the parameter list, but inline doc tags stored in parameterdescs were never
> cross-checked, allowing stale or mistyped member names to go undetected.
> 
> The new check iterates over parameterdescs keys and warns about any that
> don't appear in the parameter list, catching issues like renamed struct
> members where the documentation tag was not updated to match.
> 
> This catches real issues such as:
>   - xe_bo_types.h: @atomic_access (missing struct prefix, should be
>     @attr.atomic_access)
>   - xe_device_types.h: @usm.asid (member is actually asid_to_vm)
> 
> Variadic arguments documented as ``@args...:`` are stored in
> parameterdescs under the unstripped key (e.g. ``args...``), while
> push_parameter() strips the trailing ``...`` before appending to
> parameterlist (e.g. ``args``).  Treat the stripped form as a match so
> the new loop doesn't emit a false-positive excess-parameter warning for
> a properly documented named variadic parameter.  The bare ``@...:`` form
> is unaffected because push_parameter() does not strip when the name is
> exactly three characters.
> 
> v2: Skip variadic parameters whose documented key ends with ``...`` and
>     whose stripped name is in parameterlist, to avoid false-positive
>     "Excess function parameter 'args...'" warnings on macros like
>     ``#define foo(fmt, args...)`` documented with ``@args...:``.
> 
> Assisted-by: Claude:claude-opus-4.6
> Signed-off-by: Shuicheng Lin <shuicheng.lin@intel.com>
> ---
> Cc: Jani Nikula <jani.nikula@linux.intel.com>
> Cc: linux-doc@vger.kernel.org
> Cc: linux-kernel@vger.kernel.org
> Cc: intel-xe@lists.freedesktop.org
> ---

This patch mostly works for me. I do see one issue, but maybe it wasn't
meant to be addressed by this patch:

If I modify kthread_create() in include/linux/kthread.h to change
its @arg: to @args:, and then run scripts/kernel-doc -none -Wall, I get:

Warning: init/megaexcess.h:63 Excess function parameter 'args' description in 'kthread_create'

(that part is good)
but I would also expect to get a warning about @arg not being described.


>  tools/lib/python/kdoc/kdoc_parser.py | 36 ++++++++++++++++++++++++++++
>  1 file changed, 36 insertions(+)
> 
> diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
> index ca00695b47b3..884c6bf56d25 100644
> --- a/tools/lib/python/kdoc/kdoc_parser.py
> +++ b/tools/lib/python/kdoc/kdoc_parser.py
> @@ -673,6 +673,42 @@ 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
> +            #
> +            # Variadic arguments documented as ``@args...:`` are stored in
> +            # parameterdescs under the unstripped key (e.g. ``args...``),
> +            # while push_parameter() strips the trailing ``...`` before
> +            # appending to parameterlist (e.g. ``args``).  Treat the
> +            # stripped form as a match so this loop doesn't emit a false
> +            # positive for a properly documented variadic parameter.
> +            #
> +            if param_name.endswith("...") and \
> +               param_name[:-3] 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

-- 
~Randy