Re: [PATCH v2] docs: kdoc: fix struct_group_tagged() parsing regression

From: TAKANO Mitsuhiro

Date: Sat Nov 21 2026 - 10:03:35 EST


Hi Onana,

Thanks for the patch, and sorry it took me this long to test it. Randy
tested v1 and carried his Tested-by and Acked-by to v2 in September; the
run below is independent, on mainline d0f871bfb831 (2026-11-20).

Short version: with a fuzz-2 apply the warnings in the four headers below
go away and the test suite has no new failures. The patch needs a rebase
before it can go in. Two things below are worth a look -- the rendering
loss and the excess-warning scope -- but I do not think either has to hold
up that rebase; that is for you and the maintainers to decide.

git apply rejects the hunks in tools/lib/python/kdoc/xforms_lists.py and
tools/unittests/test_kdoc_parser.py, because of 2d72a4c09867 ("docs:
kdoc: parse context_lock_struct() as struct declaration"), which landed
after v2. The kdoc_parser.py hunk still applies. With patch -p1 those two
go in at fuzz 2. Everything below is from that tree.

Could you rebase onto current mainline and post a v3? For v3 I am only
asking for the rebase; the rendering follow-up and the excess-warning
question below are for later.

kernel-doc -Wall, warning lines (the tool prints each of these twice, so
4 -> 0 is two warnings):

include/net/page_pool/types.h 4 -> 0
include/net/libeth/rx.h 2 -> 0
include/net/libeth/xsk.h 2 -> 0
drivers/net/ethernet/intel/ice/devlink/health.h 2 -> 0

Those four files are also where the descriptions disappear. The five
warnings above are about the group names themselves; with the
xforms_lists.py hunk alone kernel-doc instead flags the 24 field
descriptions as excess, and the endswith() hunk keeps them out of that
count.

Unit tests (cd tools && /usr/bin/python3 unittests/run.py): 122 -> 123
tests; with only the test hunk the new case is the only failure beyond the
four expected ones, and with the two code hunks as well there are no new
failures.

Those results -- kernel-doc -Wall on the four headers and the unit tests,
no make htmldocs -- are what the Tested-by below covers. If the v3 hunks
come out the same as in v2 -- same added and removed lines, only offsets
and context differing -- and no other commit has touched
tools/lib/python/kdoc/, tools/unittests/ or those four headers since
d0f871bfb831, feel free to add it; if in doubt, drop it and I will re-test
and reply with a new tag.

The rendering follow-up: with v2 the field descriptions inside these
groups stop being rendered. page_pool_params renders today as
{unnamed_struct} twice plus its eleven field descriptions; with v2 it
renders the group names fast and slow, and the eleven field descriptions
are gone from kernel-doc's output. Across the four headers that is 24
descriptions, and no other file's rendered output changes -- I checked
every file that uses struct_group_tagged. They come back if those comments are
rewritten as @fast.order:, @slow.netdev: and so on, which needs the
xforms_lists.py change in this patch. I will send that rewrite as a
second patch.

The excess-warning question: the endswith() check in kdoc_parser.py also
silences excess-member warnings where a comment uses the flat name for a
nested member instead of the dotted one, in files that use no struct_group
at all -- for example 12 warning lines to 0 in include/linux/msi.h, 24 to
0 in include/linux/mroute_base.h, 20 to 0 in include/net/macsec.h and 30
to 0 in drivers/gpu/drm/panthor/panthor_device.h. Each of those is printed
twice. msi.h has no other warnings, so it goes quiet entirely; the other
three keep their unrelated ones. In msi.h, mroute_base.h, macsec.h and
panthor_device.h the rendered text does not change at all; only the excess
warnings go away. If that is wider than you intend,
restricting the check to members of a struct_group_tagged() group should
keep those warnings; I have not tried that, and the parsed members do not
record where they came from today.

The testing above was run by an AI assistant (Hermes Agent) under my
direction, and this message was drafted with it; I checked every number,
edited the text, and the tag below is mine.

Tested-by: TAKANO Mitsuhiro <takano32@xxxxxxxxx>