kernel/git/stable/linux-stable.git/tools/lib/python/kdoc, branch master

docs: xforms_lists: support DEFINE_IDTENTRY_IRQ()

2026-08-03T18:57:56+00:00

Avoid kernel-doc warnings by supported DEFINE_IDTENTRY_IRQ() as a function transform. Warning: arch/x86/kernel/apic/apic.c:2157 function parameter 'spurious_interrupt' not described in 'DEFINE_IDTENTRY_IRQ' Warning: arch/x86/kernel/apic/apic.c:2157 expecting prototype for spurious_interrupt(). Prototype was for DEFINE_IDTENTRY_IRQ() instead Signed-off-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20260723190151.507295-1-rdunlap@infradead.org>

docs: kdoc_parser: drop extraneous blank line in warning message

2026-08-03T18:07:17+00:00

Drop an extra newline (blank line) on warning messages for (2 places): expecting prototype for typedef. Prototype was for typedef {symbol} instead and expecting prototype for {struct|union}. Prototype was for struct|union {symbol} instead This makes these messages consistent with the similar enum warning, which has no extra blank line. Signed-off-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20260729052736.1423688-1-rdunlap@infradead.org>

scripts/kernel-doc: Fix kdoc for Python 3.9-3.11

2026-08-03T17:12:49+00:00

The syntax used by the excess description suggestion change works on Python 3.12+, while we need to support 3.9+. Signed-off-by: Ryszard Knop Tested-by: Akira Yokosawa Fixes: d7758384ccb4 ("scripts/kernel-doc: Suggest possible names for excess descriptions") Reported-by: Akira Yokosawa Closes: https://lore.kernel.org/22a9276d-c103-4306-a617-7f34abcd5c29@gmail.com/ Signed-off-by: Jonathan Corbet Message-ID: <20260731144508.912049-1-ryszard.knop@intel.com>

scripts/kernel-doc: Suggest possible names for excess descriptions

2026-07-22T16:10:44+00:00

Recent check_sections() change added a warning if a documentation tag member name does not match the detected struct/union member names. Since the checker knows all possible names, we can suggest known names, so that it's more obvious how to deal with the warning. Signed-off-by: Ryszard Knop Tested-by: Randy Dunlap Acked-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20260717125753.634550-1-ryszard.knop@intel.com>

docs: kdoc: fix troff output description typo

2026-07-15T16:51:27+00:00

Fix a typo in the ManFormat documentation string that describes the generated troff title header fields. Signed-off-by: Yousef Alhouseen Signed-off-by: Jonathan Corbet Message-ID: <20260624122448.4853-1-alhouseenyousef@gmail.com>

kdoc: xforms: ignore special static/inline macros

2026-06-23T20:41:52+00:00

drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm_color.c contains 7 (for now) functions that use STATIC_IFN_KUNIT or INLINE_IFN_KUNIT macros for function qualifiers (static or not, inline or not). These cause parse warnings from kernel-doc: Invalid C declaration: Expected identifier in nested name, got keyword: struct [error at 29] STATIC_IFN_KUNIT const struct drm_color_lut * __extract_blob_lut (const struct drm_property_blob *blob, uint32_t *size) Handle these in kernel-doc to prevent multiple warnings. Fixes: 647d1fd04652 ("drm/amd/display: Add KUnit test for color helpers") Signed-off-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20260612234458.1084156-1-rdunlap@infradead.org>

kdoc: xforms_lists: handle DECLARE_PER_CPU() in kernel-doc

2026-06-23T20:37:25+00:00

Add support for DECLARE_PER_CPU() as a var (variable) as used in . Warning: include/linux/netfilter/x_tables.h:345 function parameter 'seqcount_t' not described in 'DECLARE_PER_CPU' Warning: include/linux/netfilter/x_tables.h:345 function parameter 'xt_recseq' not described in 'DECLARE_PER_CPU' Signed-off-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20260614052452.1557987-1-rdunlap@infradead.org>

kernel-doc: xforms: support __SYSFS_FUNCTION_ALTERNATIVE()

2026-06-23T20:31:25+00:00

Add support for __SYSFS_FUNCTION_ALTERNATIVE() to create a union of its members (as though CONFIG_CFI is unset). Fixes these docs build warnings: WARNING: include/linux/device.h:117 Invalid param: __SYSFS_FUNCTION_ALTERNATIVE( ssize_t (*show)(struct device *dev, struct device_attribute *attr, char *buf) WARNING: include/linux/device.h:117 struct member '__SYSFS_FUNCTION_ALTERNATIVE( ssize_t (*show' not described in 'device_attribute' WARNING: include/linux/device.h:117 Invalid param: __SYSFS_FUNCTION_ALTERNATIVE( ssize_t (*store)(struct device *dev, struct device_attribute *attr, const char *buf, size_t count) WARNING: include/linux/device.h:117 struct member '__SYSFS_FUNCTION_ALTERNATIVE( ssize_t (*store' not described in 'device_attribute' Signed-off-by: Randy Dunlap Reviewed-by: Thomas Weißschuh Signed-off-by: Jonathan Corbet Message-ID: <20260623190006.406571-1-rdunlap@infradead.org>

scripts/kernel-doc: Detect mismatched inline member documentation tags

2026-05-15T14:34:13+00:00

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>

kdoc: xforms: move context attrs to function_xforms list

2026-05-15T14:15:54+00:00

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>