[PATCH v4 05/41] docs: kdoc_parser: add functions support for NestedMatch
From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Date: 2026-01-31 14:25:22
Also in:
intel-wired-lan, linux-doc, linux-hardening, lkml
Subsystem:
documentation, documentation scripts, the rest · Maintainers:
Jonathan Corbet, Mauro Carvalho Chehab, Linus Torvalds
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> Reviewed-by: Aleksandr Loktionov <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