-----Original Message-----
From: Intel-wired-lan <redacted> On Behalf
Of Mauro Carvalho Chehab
Sent: Thursday, January 29, 2026 9:08 AM
To: Jonathan Corbet <corbet@lwn.net>; Linux Doc Mailing List <linux-
doc@vger.kernel.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>;
bpf@vger.kernel.org; intel-wired-lan@lists.osuosl.org; linux-
hardening@vger.kernel.org; linux-kernel@vger.kernel.org;
netdev@vger.kernel.org; Mauro Carvalho Chehab [off-list ref];
Randy Dunlap [off-list ref]
Subject: [Intel-wired-lan] [PATCH v3 05/30] docs: kdoc_parser: add
functions support for NestedMatch

Some annotations macros may have nested parenthesis, causing normal
regex parsing to fail.

Extend apply_transforms to also use NestedMatch and add support for
nested functions.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: Randy Dunlap <redacted>
Tested-by: Randy Dunlap <redacted>
---
 tools/lib/python/kdoc/kdoc_parser.py | 38 ++++++++++++++++++---------
-
 1 file changed, 25 insertions(+), 13 deletions(-)

diff --git a/tools/lib/python/kdoc/kdoc_parser.py

b/tools/lib/python/kdoc/kdoc_parser.py
index 3ba2cda2487a..ae5b2ef80f75 100644

--- a/tools/lib/python/kdoc/kdoc_parser.py
+++ b/tools/lib/python/kdoc/kdoc_parser.py

@@ -152,7 +152,7 @@ struct_xforms = [
     (KernRe(r'DEFINE_DMA_UNMAP_LEN\s*\(' + struct_args_pattern +

r'\)', re.S), r'__u32 \1'),  ]  # -# Regexes here are guaranteed to
have the end delimiter matching
+# Struct regexes here are guaranteed to have the end delimiter
matching
 # the start delimiter. Yet, right now, only one replace group  # is
allowed.
 #

@@ -160,6 +160,13 @@ struct_nested_prefixes = [
     (re.compile(r'\bSTRUCT_GROUP\('), r'\1'),  ]

+#
+# Function Regexes here are guaranteed to have the end delimiter
+matching # the start delimiter.
+#
+function_nested_prefixes = [
+]
+
 #
 # Transforms for function prototypes
 #

@@ -207,13 +214,6 @@ var_xforms = [
 # Ancillary functions
 #

-def apply_transforms(xforms, text):
-    """
-    Apply a set of transforms to a block of text.
-    """
-    for search, subst in xforms:
-        text = search.sub(subst, text)
-    return text

 multi_space = KernRe(r'\s\s+')
 def trim_whitespace(s):

@@ -408,6 +408,8 @@ class KernelDoc:
         # Place all potential outputs into an array
         self.entries = []

+        self.nested = NestedMatch()
+
         #
         # We need Python 3.7 for its "dicts remember the insertion
         # order" guarantee

@@ -505,6 +507,16 @@ class KernelDoc:
         # State flags
         self.state = state.NORMAL

+    def apply_transforms(self, regex_xforms, nested_xforms, text):
+        """Apply a set of transforms to a block of text."""
+        for search, subst in regex_xforms:
+            text = search.sub(subst, text)
+
+        for search, sub in nested_xforms:
+            text = self.nested.sub(search, sub, text)
+
+        return text.strip()
+
     def push_parameter(self, ln, decl_type, param, dtype,
                        org_arg, declaration_name):
         """

@@ -881,11 +893,9 @@ class KernelDoc:
         # Go through the list of members applying all of our

transformations.
         #
         members = trim_private_members(members)
-        members = apply_transforms(struct_xforms, members)
+        members = self.apply_transforms(struct_xforms,
struct_nested_prefixes,
+                                        members)

-        nested = NestedMatch()
-        for search, sub in struct_nested_prefixes:
-            members = nested.sub(search, sub, members)
         #
         # Deal with embedded struct and union members, and drop enums
entirely.
         #

@@ -1088,7 +1098,9 @@ class KernelDoc:
             #
             # Apply the initial transformations.
             #
-            prototype = apply_transforms(function_xforms, prototype)
+            prototype = self.apply_transforms(function_xforms,
+

function_nested_prefixes,
+                                              prototype)

         # Yes, this truly is vile.  We are looking for:
         # 1. Return type (may be nothing if we're looking at a macro)
--
2.52.0