linux.git/tools/lib/python/kdoc/xforms_lists.py, branch v7.2-rc1

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>

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>

docs: kernel-doc: python: strip __counted_by_ptr macro

2026-05-15T14:11:36+00:00

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>

docs: xforms_lists: allow __maybe_unused in func parameters

2026-04-27T10:07:06+00:00

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>

docs: xforms_lists: use CMatch for all identifiers

2026-03-22T21:02:29+00:00

CMatch is lexically correct and replaces only identifiers,
which is exactly where macro transformations happen.

Use it to make the output safer and ensure that all arguments
will be parsed the right way, even on complex cases.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
Message-ID: <86d4a07ff0e054207747fabf38d6bb261b52b5fa.1773770483.git.mchehab+huawei@kernel.org>

docs: kdoc_parser: avoid tokenizing structs everytime

2026-03-22T21:02:29+00:00

Most of the rules inside CTransforms are of the type CMatch.

Don't re-parse the source code every time.

Doing this doesn't change the output, but makes kdoc almost
as fast as before the tokenizer patches:

    # Before tokenizer patches
    $ time ./scripts/kernel-doc . -man >original 2>&1

    real    0m42.933s
    user    0m36.523s
    sys     0m1.145s

    # After tokenizer patches
    $ time ./scripts/kernel-doc . -man >before 2>&1

    real    1m29.853s
    user    1m23.974s
    sys     0m1.237s

    # After this patch
    $ time ./scripts/kernel-doc . -man >after 2>&1

    real    0m48.579s
    user    0m45.938s
    sys     0m0.988s

    $ diff -s before after
    Files before and after are identical

Manually checked the differences between original and after
with:

    $ diff -U0 -prBw original after|grep -v Warning|grep -v "@@"|less

They're due:
  - whitespace fixes;
  - struct_group are now better handled;
  - several badly-generated man pages from broken inline kernel-doc
    markups are now fixed.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
Message-ID: <1cc2a4286ebf7d4b2d03fcaf42a1ba9fa09004b9.1773770483.git.mchehab+huawei@kernel.org>

docs: xforms_lists: better evaluate struct_group macros

2026-03-22T21:02:29+00:00

The previous approach were to unwind nested structs/unions.

Now that we have a logic that can handle it well, use it to
ensure that struct_group macros will properly reflect the
actual struct.

Note that the replacemend logic still simplifies the code
a little bit, as the basic build block for struct group is:

	union { \
		struct { MEMBERS } ATTRS; \
		struct __struct_group_tag(TAG) { MEMBERS } ATTRS NAME; \
	} ATTRS

There:

- ATTRS is meant to add extra macro attributes like __packed
  which we already discard, as they aren't relevant to
  document struct members;

- TAG is used only when built with __cplusplus.

So, instead, convert them into just:

    struct { MEMBERS };

Please notice that here, we're using the greedy version of the
backrefs, as MEMBERS is actually MEMBERS... on all such macros.

Signed-off-by: Mauro Carvalho Chehab 
Reviewed-by: Aleksandr Loktionov 
Signed-off-by: Jonathan Corbet 
Message-ID: <24bf2c036b08814d9b4aabc27542fd3b2ff54424.1773770483.git.mchehab+huawei@kernel.org>

docs: xforms_lists: handle struct_group directly

2026-03-22T21:02:29+00:00

The previous logic was handling struct_group on two steps.
Remove the previous approach, as CMatch can do it the right
way on a single step.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
Message-ID: