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

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>

Merge tag 'libcrypto-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/ebiggers/linux

2026-04-21T18:46:22+00:00

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()

docs: kdoc: Expand 'at_least' when creating parameter list

2026-04-19T00:32:01+00:00

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 
Reviewed-by: Ard Biesheuvel 
Acked-by: Randy Dunlap 
Tested-by: Randy Dunlap 
Link: https://lore.kernel.org/r/20260418192138.15556-2-ebiggers@kernel.org
Signed-off-by: Eric Biggers

docs: kdoc: better handle source when producing YAML output

2026-03-25T19:36:46+00:00

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 
Signed-off-by: Jonathan Corbet 
Message-ID: <77902dafabb5c3250486aa2dc1568d5fafa95c5b.1774256269.git.mchehab+huawei@kernel.org>

docs: kernel-doc: add support to store output on a YAML file

2026-03-22T21:10:40+00:00

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 
Signed-off-by: Jonathan Corbet 
Message-ID:

docs: kdoc_item: fix a typo on sections_start_lines

2026-03-22T21:10:40+00:00

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 
Signed-off-by: Jonathan Corbet 
Message-ID:

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: kdoc: ensure that comments are dropped before calling split_struct_proto()

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

Changeset 2b957decdb6c ("docs: kdoc: don't add broken comments inside prototypes")
revealed a hidden bug at split_struct_proto(): some comments there may break
its capability of properly identifying a struct.

Fixing it is as simple as stripping comments before calling it.

Fixes: 2b957decdb6c ("docs: kdoc: don't add broken comments inside prototypes")
Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
Message-ID:

docs: c_lex: setup a logger to report tokenizer issues

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

Report file that has issues detected via CMatch and CTokenizer.

This is done by setting up a logger that will be overriden by
kdoc_parser, when used on it.

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

docs: kdoc: replace NestedMatch with CMatch

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

Our previous approach to solve nested structs were to use
NestedMatch. It works well, but adding support to parse delimiters
is very complex.

Instead, use CMatch, which uses a C tokenizer, making the code more
reliable and simpler.

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