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

[Randy Dunlap]

On 5/6/26 7:32 PM, 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)
> 
> While at it, fix two long-standing issues with named variadic parameters
> (macros like ``#define foo(fmt, args...)``) that the new check exposed:
> 
>   1. A description provided via the ``@args...:`` doc form was stored
>      in parameterdescs under the unstripped key ``args...``, while
>      push_parameter() stripped the trailing ``...`` and only added
>      ``args`` to parameterlist.  As a result the user-supplied
>      description was orphaned, parameterdescs[``args``] was auto-
>      populated with the generic "variable arguments" text, and the
>      user's actual description was silently discarded by the output
>      stage.  Migrate the description from the unstripped to the
>      stripped key inside push_parameter() so the user's text reaches
>      the output and the new check does not flag the orphaned key.
> 
>   2. push_parameter() always auto-populated parameterdescs[param] with
>      "variable arguments" for variadic parameters, which bypassed the
>      existing "parameter not described" warning at line 549.  As a
>      consequence, a named variadic with no matching ``@<name>:`` doc
>      tag (or a mistyped one such as ``@args:`` for a parameter named
>      ``arg``) went undetected.  Emit the standard "not described"
>      warning for named variadics before applying the auto-fill, so
>      missing or mistyped variadic docs are reported just like missing
>      docs for any other parameter.  The bare ``@...:`` form is
>      unaffected because it has no natural name for the user to
>      document.
> 
> This second hunk surfaces one real pre-existing documentation gap in
> include/linux/hashtable.h: hash_for_each_possible_rcu()'s ``cond...``
> parameter has no matching ``@cond:`` doc entry.  No false positives were
> observed across include/linux, kernel/, or drivers/gpu/drm.
> 
> 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...:``.
> 
> v3: The v2 special case in check_sections() only suppressed the warning
>     while still letting the user's description be silently dropped from
>     the generated output.  Replace it with a fix in push_parameter() that
>     migrates the description from ``args...`` to ``args`` when the name
>     is stripped, so the user's text is preserved end-to-end and the
>     new excess-parameter check naturally finds nothing to flag.
> 
> v4: Also emit the standard "parameter not described" warning for named
>     variadics that have no matching ``@<name>:`` doc tag.  Previously
>     push_parameter()'s unconditional auto-fill bypassed that warning,
>     so a missing or mistyped variadic doc went undetected. (Randy)
> 
> Assisted-by: Claude:claude-opus-4.6
> Signed-off-by: Shuicheng Lin <shuicheng.lin@xxxxxxxxx>

Tested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
Acked-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>

Thanks. This is good stuff.

> ---
> Cc: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
> Cc: Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx>
> Cc: linux-kernel@xxxxxxxxxxxxxxx
> Cc: intel-xe@xxxxxxxxxxxxxxxxxxxxx
> ---
>  tools/lib/python/kdoc/kdoc_parser.py | 54 +++++++++++++++++++++++++++-
>  1 file changed, 53 insertions(+), 1 deletion(-)
> 
> diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
> index ca00695b47b3..2bc49c3ece14 100644
> --- a/tools/lib/python/kdoc/kdoc_parser.py
> +++ b/tools/lib/python/kdoc/kdoc_parser.py
> @@ -512,9 +512,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":
> @@ -673,6 +700,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

-- 
~Randy