[PATCH] docs: xforms_lists: handle __cacheline_group_{begin,end}_aligned()

[Prateekshit Jaiswal via B4 Relay <devnull+prateekshitjaiswal73.gmail.com@kernel.org>]

From: Prateekshit Jaiswal <prateekshitjaiswal73@gmail.com>

kernel-doc treats each __cacheline_group_{begin,end}_aligned() call as
an undescribed struct member:

  Warning: drivers/net/ethernet/intel/idpf/idpf_txrx.h:436 struct member '__cacheline_group_begin_aligned(read_mostly' not described in 'idpf_q_vector'

Those markers are defined in include/linux/cache.h. A former special
case in push_parameter() dropped any member whose name contained
"__cacheline_group", which covered both the plain and _aligned forms.
Commit 8b00d6fe9696 ("docs: kdoc: trim __cacheline_group_* with the
other annotations") replaced that with a transform that only matches
__cacheline_group_begin() and __cacheline_group_end().

The pattern kept that shape when it later moved to CMatch, which
requires a word boundary right after the name. Since "_aligned"
continues the identifier, the suffix still cannot match.

Make the suffix optional, keep the copy of the rule in test_cmatch.py
in sync, and add a kdoc-test.yaml case based on struct idpf_q_vector
that fails without this change. The expected definition still has the
lone ';' that each stripped marker leaves behind, as the unaligned
markers already do.

Running "kernel-doc -none -Wall" over every file with kernel-doc
comments on docs-next, this removes 34 distinct warnings, all in
idpf_txrx.h, and adds none.

The problem was found, and the fix and test drafted, with the help of
an AI coding assistant (Claude Code); I have reviewed and tested the
result.

Fixes: 8b00d6fe9696 ("docs: kdoc: trim __cacheline_group_* with the other annotations")
Signed-off-by: Prateekshit Jaiswal <prateekshitjaiswal73@gmail.com>
---
Testing:
- tools/unittests/run.py: all 125 tests pass; the new test fails when
  only the xforms_lists.py change is reverted.
- kernel-doc -none -Wall over all files with kernel-doc comments,
  before and after: 34 warnings removed, none added.

This is based on docs-next. In linux-next, the kspp tree adds
__require_explicit_initialization to struct_xforms three lines above
the changed one, so the context differs there; the patch still applies
with reduced context and the resolution is trivial.

The lone ';' left in the rendered definition (also seen today for the
plain markers, e.g. struct net_device) appeared with commit 7538df7a2d7d
("docs: xforms_lists: use CMatch for all identifiers"). It is left for
a separate change, which would then also update the new test.
---
 tools/lib/python/kdoc/xforms_lists.py |  2 +-
 tools/unittests/kdoc-test.yaml        | 72 +++++++++++++++++++++++++++++++++++
 tools/unittests/test_cmatch.py        |  2 +-
 3 files changed, 74 insertions(+), 2 deletions(-)

diff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/xforms_lists.py
index db23fb650ea8..fa380055191c 100644
--- a/tools/lib/python/kdoc/xforms_lists.py
+++ b/tools/lib/python/kdoc/xforms_lists.py
@@ -38,7 +38,7 @@ class CTransforms:
         (CMatch("__rcu"), ""),
         (CMatch("____cacheline_aligned_in_smp"), ""),
         (CMatch("____cacheline_aligned"), ""),
-        (CMatch("__cacheline_group_(?:begin|end)"), ""),
+        (CMatch("__cacheline_group_(?:begin|end)(?:_aligned)?"), ""),
         (CMatch("__ETHTOOL_DECLARE_LINK_MODE_MASK"), r"DECLARE_BITMAP(\1, __ETHTOOL_LINK_MODE_MASK_NBITS)"),
         (CMatch("DECLARE_PHY_INTERFACE_MASK",),r"DECLARE_BITMAP(\1, PHY_INTERFACE_MODE_MAX)"),
         (CMatch("DECLARE_BITMAP"), r"unsigned long \1[BITS_TO_LONGS(\2)]"),
diff --git a/tools/unittests/kdoc-test.yaml b/tools/unittests/kdoc-test.yaml
index 14d36daa1bba..da396f975cb5 100644
--- a/tools/unittests/kdoc-test.yaml
+++ b/tools/unittests/kdoc-test.yaml
@@ -1696,3 +1696,75 @@ tests:
 
         ``spinlock_t *lock``
           the spinlock
+- name: struct_cacheline_group_aligned
+  description: "Strip __cacheline_group_{begin,end}_aligned() markers from a struct"
+  fname: drivers/net/ethernet/intel/idpf/idpf_txrx.h
+  source: |
+    /**
+     * struct idpf_q_vector
+     * @vport: Vport back pointer
+     * @num_rxq: Number of RX queues
+     * @napi: napi handler
+     * @v_idx: Vector index
+     */
+    struct idpf_q_vector {
+            __cacheline_group_begin_aligned(read_mostly);
+            struct idpf_vport *vport;
+
+            u16 num_rxq;
+            __cacheline_group_end_aligned(read_mostly);
+
+            __cacheline_group_begin_aligned(read_write);
+            struct napi_struct napi;
+            __cacheline_group_end_aligned(read_write);
+
+            __cacheline_group_begin_aligned(cold);
+            u16 v_idx;
+
+            __cacheline_group_end_aligned(cold);
+    };
+  expected:
+  - kdoc_item:
+      name: idpf_q_vector
+      type: struct
+      declaration_start_line: 1
+      sections: {}
+      sections_start_lines: {}
+      parameterlist:
+      - vport
+      - num_rxq
+      - napi
+      - v_idx
+      parameterdesc_start_lines:
+        vport: 2
+        num_rxq: 3
+        napi: 4
+        v_idx: 5
+      parameterdescs:
+        vport: |
+          Vport back pointer
+        num_rxq: |
+          Number of RX queues
+        napi: |
+          napi handler
+        v_idx: |
+          Vector index
+      parametertypes:
+        vport: struct idpf_vport *vport
+        num_rxq: u16 num_rxq
+        napi: struct napi_struct napi
+        v_idx: u16 v_idx
+      warnings: []
+      other_stuff:
+        definition: |
+          ;
+          struct idpf_vport *vport;
+          u16 num_rxq;
+          ;
+          ;
+          struct napi_struct napi;
+          ;
+          ;
+          u16 v_idx;
+          ;
+        purpose: ''
diff --git a/tools/unittests/test_cmatch.py b/tools/unittests/test_cmatch.py
index 109141cd2ab8..02d63a51c05e 100755
--- a/tools/unittests/test_cmatch.py
+++ b/tools/unittests/test_cmatch.py
@@ -324,7 +324,7 @@ class TestSubWithLocalXforms(TestCaseDiff):
         (CMatch('__guarded_by'), ' '),
         (CMatch('__pt_guarded_by'), ' '),
 
-        (CMatch('__cacheline_group_(begin|end)'), ''),
+        (CMatch('__cacheline_group_(begin|end)(_aligned)?'), ''),
 
         (CMatch('struct_group'), r'\2'),
         (CMatch('struct_group_attr'), r'\3'),

---
base-commit: 2649344d20dfb13e30b560f06138229d8e40350a
change-id: 20261107-kdoc-cacheline-aligned-75f1ad0a8c14

Best regards,
-- 
Prateekshit Jaiswal <prateekshitjaiswal73@gmail.com>