From 713e899a683eb764b645eaeab79e7308cda497a7 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sat, 11 Apr 2026 16:35:26 -0700 Subject: docs: xforms_lists: allow __maybe_unused in func parameters Bart has a patch (not yet merged) that causes kernel-doc warnings: WARNING: ./include/linux/highmem.h:235 function parameter '__maybe_unused' not described in 'clear_user_pages' Documentation/mm/highmem:211: ./include/linux/highmem.h:222: WARNING: Error in declarator or parameters Handle this by adding "__maybe_unused" to the list of known function parameter modifiers. Reported-by: kernel test robot Closes: https://lore.kernel.org/oe-kbuild-all/202604120025.jtlnpWff-lkp@intel.com/ Signed-off-by: Randy Dunlap Cc: Bart Van Assche Reviewed-by: Bart Van Assche Signed-off-by: Jonathan Corbet Message-ID: <20260411233526.3909303-1-rdunlap@infradead.org> --- tools/lib/python/kdoc/xforms_lists.py | 1 + 1 file changed, 1 insertion(+) (limited to 'tools/lib/python') diff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/xforms_lists.py index f6ea9efb11ae..496c52188273 100644 --- a/tools/lib/python/kdoc/xforms_lists.py +++ b/tools/lib/python/kdoc/xforms_lists.py @@ -93,6 +93,7 @@ class CTransforms: (CMatch("__weak"), ""), (CMatch("__sched"), ""), (CMatch("__always_unused"), ""), + (CMatch("__maybe_unused"), ""), (CMatch("__printf"), ""), (CMatch("__(?:re)?alloc_size"), ""), (CMatch("__diagnose_as"), ""), -- cgit v1.2.3 From 8bf5a177c318737c53e53299eac781a94ad632af Mon Sep 17 00:00:00 2001 From: Tudor Ambarus Date: Wed, 6 May 2026 11:04:12 +0000 Subject: docs: kernel-doc: python: strip __counted_by_ptr macro The `__counted_by_ptr` macro was recently introduced [1] to extend bounds checking semantics to standard dynamically allocated pointers. However, the new Python implementation of kernel-doc does not currently recognize it as a compiler attribute. When kernel-doc encounters a struct member annotated with this macro, it fails to parse the variable name correctly, resulting in false-positive warnings like: Warning: ... struct member '__counted_by_ptr(cmdcnt' not described Add `__counted_by_ptr` to the `struct_xforms` regex list so it gets safely stripped out during the parsing phase, mirroring the existing behavior for `__counted_by`. Update the corresponding unit tests. Link: https://git.kernel.org/torvalds/c/150a04d817d8 [1] Signed-off-by: Tudor Ambarus Reviewed-by: Mauro Carvalho Chehab Reviewed-by: Kees Cook Acked-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20260506-kdoc-__counted_by_ptr-v1-1-70763486871f@linaro.org> --- tools/lib/python/kdoc/xforms_lists.py | 1 + tools/unittests/test_cmatch.py | 1 + 2 files changed, 2 insertions(+) (limited to 'tools/lib/python') diff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/xforms_lists.py index 496c52188273..8753dd539f23 100644 --- a/tools/lib/python/kdoc/xforms_lists.py +++ b/tools/lib/python/kdoc/xforms_lists.py @@ -29,6 +29,7 @@ class CTransforms: (CMatch("__aligned"), ""), (CMatch("__counted_by"), ""), (CMatch("__counted_by_(le|be)"), ""), + (CMatch("__counted_by_ptr"), ""), (CMatch("__guarded_by"), ""), (CMatch("__pt_guarded_by"), ""), (CMatch("__packed"), ""), diff --git a/tools/unittests/test_cmatch.py b/tools/unittests/test_cmatch.py index 7b996f83784d..109141cd2ab8 100755 --- a/tools/unittests/test_cmatch.py +++ b/tools/unittests/test_cmatch.py @@ -320,6 +320,7 @@ class TestSubWithLocalXforms(TestCaseDiff): (CMatch('__aligned'), ' '), (CMatch('__counted_by'), ' '), (CMatch('__counted_by_(le|be)'), ' '), + (CMatch('__counted_by_ptr'), ' '), (CMatch('__guarded_by'), ' '), (CMatch('__pt_guarded_by'), ' '), -- cgit v1.2.3 From 026d7010f13da6371317eb9269e95e5886abb39b Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Tue, 5 May 2026 15:15:48 -0700 Subject: kdoc: xforms: move context attrs to function_xforms list The context analysis macros are function attributes that should be in the function_xforms list. Somewhere along the way they were inserted into the struct_xforms list instead. This causes docs build warnings to continue to be emitted for context macros. Move the context analysis macros to the function_xforms list where they should be to eliminate these warnings. Documentation/core-api/kref:328: ../include/linux/kref.h:72: WARNING: Invalid C declaration: Expected end of definition. [error at 96] int kref_put_mutex (struct kref *kref, void (*release)(struct kref *kref), struct mutex *mutex) __cond_acquires(true# mutex) Documentation/core-api/kref:328: ../include/linux/kref.h:94: WARNING: Invalid C declaration: Expected end of definition. [error at 92] int kref_put_lock (struct kref *kref, void (*release)(struct kref *kref), spinlock_t *lock) __cond_acquires(true# lock) Signed-off-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20260505221548.163751-1-rdunlap@infradead.org> --- tools/lib/python/kdoc/xforms_lists.py | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) (limited to 'tools/lib/python') diff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/xforms_lists.py index 8753dd539f23..aab70e5eaa6f 100644 --- a/tools/lib/python/kdoc/xforms_lists.py +++ b/tools/lib/python/kdoc/xforms_lists.py @@ -49,16 +49,6 @@ class CTransforms: (CMatch("DEFINE_DMA_UNMAP_ADDR"), r"dma_addr_t \1"), (CMatch("DEFINE_DMA_UNMAP_LEN"), r"__u32 \1"), (CMatch("VIRTIO_DECLARE_FEATURES"), r"union { u64 \1; u64 \1_array[VIRTIO_FEATURES_U64S]; }"), - (CMatch("__cond_acquires"), ""), - (CMatch("__cond_releases"), ""), - (CMatch("__acquires"), ""), - (CMatch("__releases"), ""), - (CMatch("__must_hold"), ""), - (CMatch("__must_not_hold"), ""), - (CMatch("__must_hold_shared"), ""), - (CMatch("__cond_acquires_shared"), ""), - (CMatch("__acquires_shared"), ""), - (CMatch("__releases_shared"), ""), (CMatch("__attribute__"), ""), # @@ -99,6 +89,16 @@ class CTransforms: (CMatch("__(?:re)?alloc_size"), ""), (CMatch("__diagnose_as"), ""), (CMatch("DECL_BUCKET_PARAMS"), r"\1, \2"), + (CMatch("__cond_acquires"), ""), + (CMatch("__cond_releases"), ""), + (CMatch("__acquires"), ""), + (CMatch("__releases"), ""), + (CMatch("__must_hold"), ""), + (CMatch("__must_not_hold"), ""), + (CMatch("__must_hold_shared"), ""), + (CMatch("__cond_acquires_shared"), ""), + (CMatch("__acquires_shared"), ""), + (CMatch("__releases_shared"), ""), (CMatch("__no_context_analysis"), ""), (CMatch("__attribute_const__"), ""), (CMatch("__attribute__"), ""), -- cgit v1.2.3 From 46d9c16115cf046ce564f0230126cae785f73826 Mon Sep 17 00:00:00 2001 From: Shuicheng Lin Date: Thu, 7 May 2026 02:32:32 +0000 Subject: scripts/kernel-doc: Detect mismatched inline member documentation tags 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 ``@:`` 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 ``@:`` 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 Tested-by: Randy Dunlap Acked-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20260507023232.4108680-1-shuicheng.lin@intel.com> --- tools/lib/python/kdoc/kdoc_parser.py | 54 +++++++++++++++++++++++++++++++++++- 1 file changed, 53 insertions(+), 1 deletion(-) (limited to 'tools/lib/python') 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 ``@:`` 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 -- cgit v1.2.3