> -----Original Message-----
> From: Intel-wired-lan <intel-wired-lan-bounces@osuosl.org> 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 <mchehab@kernel.org>;
> Randy Dunlap <rdunlap@infradead.org>
> 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 <rdunlap@infradead.org>
> Tested-by: Randy Dunlap <rdunlap@infradead.org>
> ---
> 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
Reviewed-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com>