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 <ryszard.knop@intel.com>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260717125753.634550-1-ryszard.knop@intel.com>
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: 647d1fd046 ("drm/amd/display: Add KUnit test for color helpers")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260612234458.1084156-1-rdunlap@infradead.org>
Add support for DECLARE_PER_CPU() as a var (variable) as used in
<linux/netfilter/x_tables.h>.
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 <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260614052452.1557987-1-rdunlap@infradead.org>
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 <rdunlap@infradead.org>
Reviewed-by: Thomas Weißschuh <linux@weissschuh.net>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260623190006.406571-1-rdunlap@infradead.org>
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@intel.com>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260507023232.4108680-1-shuicheng.lin@intel.com>
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 <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260505221548.163751-1-rdunlap@infradead.org>
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 <tudor.ambarus@linaro.org>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Kees Cook <kees@kernel.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260506-kdoc-__counted_by_ptr-v1-1-70763486871f@linaro.org>
Pull more crypto library updates from Eric Biggers:
"Crypto library fix and documentation update:
- Fix an integer underflow in the mpi library
- Improve the crypto library documentation"
* tag 'libcrypto-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/ebiggers/linux:
lib/crypto: docs: Add rst documentation to Documentation/crypto/
docs: kdoc: Expand 'at_least' when creating parameter list
lib/crypto: mpi: Fix integer underflow in mpi_read_raw_from_sgl()
sphinx doesn't know that the kernel headers do:
#define at_least static
Do this replacement before declarations are passed to it.
This prevents errors like the following from appearing once the
lib/crypto/ kernel-doc is wired up to the sphinx build:
linux/Documentation/crypto/libcrypto:128: ./include/crypto/sha2.h:773: WARNING: Error in declarator or parameters
Error in declarator or parameters
Invalid C declaration: Expected ']' in end of array operator. [error at 59]
void sha512_final (struct sha512_ctx *ctx, u8 out[at_least SHA512_DIGEST_SIZE])
Acked-by: Jonathan Corbet <corbet@lwn.net>
Reviewed-by: Ard Biesheuvel <ardb@kernel.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/20260418192138.15556-2-ebiggers@kernel.org
Signed-off-by: Eric Biggers <ebiggers@kernel.org>
The current logic was storing symbols source code on a list,
not linked to the actual KdocItem. While this works fine when
kernel-doc markups are OK, on places where there is a "/**"
without a valid kernel-doc markup, it ends that the 1:1 match
between source code and KdocItem doesn't happen, causing
problems to generate the YAML output.
Fix it by storing the source code directly into the KdocItem
structure.
This shouldn't affect performance or memory footprint, except
when --yaml option is used.
While here, add a __repr__() function for KdocItem, as it
helps debugging it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <77902dafabb5c3250486aa2dc1568d5fafa95c5b.1774256269.git.mchehab+huawei@kernel.org>
Fix check for simple table delimiters.
ReST simple tables use "=" instead of "-". I ended testing it with
a table modified from a complex one, using "--- --- ---", instead
of searching for a real Kernel example.
Only noticed when adding an unit test and seek for an actual
example from kernel-doc markups.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <dea95337c05040f95e5a95ae41d69ddef0aaa8d6.1774256269.git.mchehab+huawei@kernel.org>
Currently, there are 15 occurrences of section?_start_lines,
with 10 using the plural way.
This is an issue, as, while kdoc_output works with KdocItem,
the term doesn't match its init value.
The variable sections_start_lines stores multiple sections,
so placing it in plural is its correct way.
So, ensure that, on all parts of kdoc, this will be referred
as sections_start_lines.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <d1e0f1d3f80df41c11a1bbde6a12fd9468bc3813.1773823995.git.mchehab+huawei@kernel.org>
When reading the contents on a KdocItem using YAML, the data
will be imported into a dict.
Add a method to create a new KdocItem from a dict to allow
converting such input into a real KdocItem.
While here, address an issue that, if the class is initialized
with an internal parameter outside the 4 initial arguments,
it would end being added inside other_stuff, which breaks
initializing it from a dict.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <fafeac23d1577927e1a3c32cddfbec1e0209ac73.1773823995.git.mchehab+huawei@kernel.org>
When writing unittests for kdoc_output, it became clear that
the logic with handles a series of KdocItem symbols from
a single file belons to kdoc_output, and not to kdoc_files.
Move the code to it.
While here, also ensure that self.config will be placed
together with set.out_style.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <4ebc26e37a0b544c50d50b8077760f147fa6a535.1773823995.git.mchehab+huawei@kernel.org>
