[Intel-wired-lan] [PATCH 05/38] docs: kdoc_parser: add functions support for NestedMatch

Mauro Carvalho Chehab
2026-02-18T10:13:30Z

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 <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com>
---
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 9643ffb7584a..af0ab732048b 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
#
@@ -208,13 +215,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):
@@ -409,6 +409,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
@@ -506,6 +508,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):
"""
@@ -882,11 +894,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.
#
@@ -1089,7 +1099,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