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@xxxxxxxxx>
> ---
> Cc: Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx>
> Cc: linux-doc@xxxxxxxxxxxxxxx
> Cc: linux-kernel@xxxxxxxxxxxxxxx
> Cc: intel-xe@xxxxxxxxxxxxxxxxxxxxx
> ---

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