| 47646ce1 | 08-Aug-2026 |
Alison Schofield <alison.schofield@intel.com> |
docs: python: abi_regex: convert adjacent index placeholders
While validating recent CXL ABI documentation updates with
get_abi.py, every decoderX.Y entry was reported as undocumented.
The placehol
docs: python: abi_regex: convert adjacent index placeholders
While validating recent CXL ABI documentation updates with
get_abi.py, every decoderX.Y entry was reported as undocumented.
The placeholder conversion mishandles adjacent index placeholders,
producing patterns that cannot match the corresponding sysfs paths.
As a result, valid ABI entries are reported as undocumented.
Handle adjacent placeholders independently so generated patterns match
the documented paths. This fixes decoderX.Y entries in the CXL ABI and
other ABI documentation that uses the same naming convention.
Signed-off-by: Alison Schofield <alison.schofield@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <cc893dca3aaa3ec833ba70d1f32c3e7342b7faf2.1786139549.git.alison.schofield@intel.com>
show more ...
|
| 02299dcd | 08-Aug-2026 |
Alison Schofield <alison.schofield@intel.com> |
docs: python: abi_regex: catch the right exception for a bad regex
While validating recent CXL ABI documentation updates with
get_abi.py, the 'undefined' mode was found to abort instead of
reporting
docs: python: abi_regex: catch the right exception for a bad regex
While validating recent CXL ABI documentation updates with
get_abi.py, the 'undefined' mode was found to abort instead of
reporting undocumented ABI entries.
Older Python releases raise re.error, while newer releases expose
re.PatternError. Catching the compatible re.error exception handles
both cases.
Use re.error so the scan continues and reports the remaining
results.
Signed-off-by: Alison Schofield <alison.schofield@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <9f6fa7a9aa6ba9a26b484b911976713356b3fd44.1786139549.git.alison.schofield@intel.com>
show more ...
|
| 3046f4be | 29-Jul-2026 |
Randy Dunlap <rdunlap@infradead.org> |
docs: kdoc_parser: drop extraneous blank line in warning message
Drop an extra newline (blank line) on warning messages for (2 places):
expecting prototype for typedef. Prototype was for typedef {
docs: kdoc_parser: drop extraneous blank line in warning message
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 <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260729052736.1423688-1-rdunlap@infradead.org>
show more ...
|
| 5ffcd42a | 31-Jul-2026 |
Ryszard Knop <ryszard.knop@intel.com> |
scripts/kernel-doc: Fix kdoc for Python 3.9-3.11
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 <rysza
scripts/kernel-doc: Fix kdoc for Python 3.9-3.11
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 <ryszard.knop@intel.com>
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Fixes: d7758384ccb4 ("scripts/kernel-doc: Suggest possible names for excess descriptions")
Reported-by: Akira Yokosawa <akiyks@gmail.com>
Closes: https://lore.kernel.org/22a9276d-c103-4306-a617-7f34abcd5c29@gmail.com/
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260731144508.912049-1-ryszard.knop@intel.com>
show more ...
|
| d42197c7 | 13-Jun-2026 |
Randy Dunlap <rdunlap@infradead.org> |
kdoc: xforms: ignore special static/inline macros
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
func
kdoc: xforms: ignore special static/inline macros
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 <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260612234458.1084156-1-rdunlap@infradead.org>
show more ...
|
| 46d9c161 | 07-May-2026 |
Shuicheng Lin <shuicheng.lin@intel.com> |
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 s
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 ``@<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>
show more ...
|
| 026d7010 | 06-May-2026 |
Randy Dunlap <rdunlap@infradead.org> |
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 in
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 <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260505221548.163751-1-rdunlap@infradead.org>
show more ...
|
| 07f6cb18 | 26-Mar-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
tools: unittest_helper: add a quiet mode
On quiet mode, only report errors.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-
tools: unittest_helper: add a quiet mode
On quiet mode, only report errors.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <27556792ff70e6267ecd19c258149d380db8d423.1774551940.git.mchehab+huawei@kernel.org>
show more ...
|
| d642acfd | 27-Mar-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
doc tools: better handle KBUILD_VERBOSE
As reported by Jacob, there are troubles when KBUILD_VERBOSE is
set at the environment.
Fix it on both kernel-doc and sphinx-build-wrapper.
Reported-by: Jac
doc tools: better handle KBUILD_VERBOSE
As reported by Jacob, there are troubles when KBUILD_VERBOSE is
set at the environment.
Fix it on both kernel-doc and sphinx-build-wrapper.
Reported-by: Jacob Keller <jacob.e.keller@intel.com>
Closes: https://lore.kernel.org/linux-doc/9367d899-53af-4d9c-9320-22fc4dbadca5@intel.com/
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Tested-by: Jacob Keller <jacob.e.keller@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <7a99788db75630fb14828d612c0fd77c45ec1891.1774591065.git.mchehab+huawei@kernel.org>
show more ...
|
| 2ca0b54d | 23-Mar-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
docs: c_lex.py: store logger on its data
By having the logger stored there, any code using CTokenizer can
log messages there.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed
docs: c_lex.py: store logger on its data
By having the logger stored there, any code using CTokenizer can
log messages there.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <467979dc18149e4b2a7113c178e0cb07919632f2.1774256269.git.mchehab+huawei@kernel.org>
show more ...
|
| 9c391181 | 23-Mar-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
docs: kdoc_output: raise an error if full_proto not available for var
This is mandatory, but if it is missing, we need to know what
symbol had problems.
Signed-off-by: Mauro Carvalho Chehab <mcheha
docs: kdoc_output: raise an error if full_proto not available for var
This is mandatory, but if it is missing, we need to know what
symbol had problems.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <0c3d9dd25889784b999efdb354ade48264c0e03c.1774256269.git.mchehab+huawei@kernel.org>
show more ...
|
| e786fab2 | 23-Mar-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
docs: kdoc_yaml_file: use a better name for the tests
Instead of always using a name with a number on it, use
the name of the object directly whenever possible.
When the name is already used, appen
docs: kdoc_yaml_file: use a better name for the tests
Instead of always using a name with a number on it, use
the name of the object directly whenever possible.
When the name is already used, append a number prefix at
the end.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <d1c4cd94547d843af0debf9e317e006d55d705f1.1774256269.git.mchehab+huawei@kernel.org>
show more ...
|
| 99ec67a9 | 23-Mar-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
docs: kdoc: better handle source when producing YAML output
The current logic was storing symbols source code on a list,
not linked to the actual KdocItem. While this works fine when
kernel-doc mark
docs: kdoc: better handle source when producing YAML output
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>
show more ...
|
| 8326e4a2 | 23-Mar-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
docs: kdoc_output: fix handling of simple tables
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
docs: kdoc_output: fix handling of simple tables
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>
show more ...
|
| 6e0d7b63 | 23-Mar-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
docs: kdoc_yaml_file: add a representer to make strings look nicer
The strings representation is not ok, currently. Add a helper
function to improve it, and drop blank lines at beginning and
at the
docs: kdoc_yaml_file: add a representer to make strings look nicer
The strings representation is not ok, currently. Add a helper
function to improve it, and drop blank lines at beginning and
at the end of the dumps
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <422041a8b49b2609de5749092fe074b7948c32a6.1774256269.git.mchehab+huawei@kernel.org>
show more ...
|
| 01d6d7bf | 18-Mar-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
docs: kernel-doc: add support to store output on a YAML file
Add a command line parameter and library support to optionally
store:
- KdocItem intermediate format after parsing;
- man pages output;
-
docs: kernel-doc: add support to store output on a YAML file
Add a command line parameter and library support to optionally
store:
- KdocItem intermediate format after parsing;
- man pages output;
- rst output.
inside a YAML file.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <ba54277b3c909867153b9547dfa33c1831ca35d9.1773823995.git.mchehab+huawei@kernel.org>
show more ...
|