{"id":2197661,"url":"http://patchwork.ozlabs.org/api/1.0/patches/2197661/?format=json","project":{"id":46,"url":"http://patchwork.ozlabs.org/api/1.0/projects/46/?format=json","name":"Intel Wired Ethernet development","link_name":"intel-wired-lan","list_id":"intel-wired-lan.osuosl.org","list_email":"intel-wired-lan@osuosl.org","web_url":"","scm_url":"","webscm_url":""},"msgid":"","date":"2026-02-18T10:12:49","name":"[19/38] docs: kdoc_re: make NestedMatch use KernRe","commit_ref":null,"pull_url":null,"state":"handled-elsewhere","archived":false,"hash":"5eac2f8a3b702928ec92fa2a553d85b29c91547c","submitter":{"id":78235,"url":"http://patchwork.ozlabs.org/api/1.0/people/78235/?format=json","name":"Mauro Carvalho Chehab","email":"mchehab+huawei@kernel.org"},"delegate":null,"mbox":"http://patchwork.ozlabs.org/project/intel-wired-lan/patch/a27f96e3e6e2b58bf1e4e7aab8a592d81f32887f.1771408406.git.mchehab+huawei@kernel.org/mbox/","series":[{"id":492532,"url":"http://patchwork.ozlabs.org/api/1.0/series/492532/?format=json","date":"2026-02-18T10:12:30","name":"docs: several improvements to kernel-doc","version":1,"mbox":"http://patchwork.ozlabs.org/series/492532/mbox/"}],"check":"pending","checks":"http://patchwork.ozlabs.org/api/patches/2197661/checks/","tags":{},"headers":{"Return-Path":"","X-Original-To":["incoming@patchwork.ozlabs.org","intel-wired-lan@lists.osuosl.org"],"Delivered-To":["patchwork-incoming@legolas.ozlabs.org","intel-wired-lan@lists.osuosl.org"],"Authentication-Results":["legolas.ozlabs.org;\n\tdkim=pass (2048-bit key;\n unprotected) header.d=osuosl.org header.i=@osuosl.org header.a=rsa-sha256\n header.s=default header.b=MEkoqPNo;\n\tdkim-atps=neutral","legolas.ozlabs.org;\n spf=pass (sender SPF authorized) smtp.mailfrom=osuosl.org\n (client-ip=2605:bc80:3010::136; helo=smtp3.osuosl.org;\n envelope-from=intel-wired-lan-bounces@osuosl.org;\n receiver=patchwork.ozlabs.org)"],"Received":["from smtp3.osuosl.org (smtp3.osuosl.org [IPv6:2605:bc80:3010::136])\n\t(using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)\n\t key-exchange x25519 server-signature ECDSA (secp384r1) server-digest SHA384)\n\t(No client certificate requested)\n\tby legolas.ozlabs.org (Postfix) with ESMTPS id 4fGC5W3JrJz1xwr\n\tfor ; Wed, 18 Feb 2026 21:13:35 +1100 (AEDT)","from localhost (localhost [127.0.0.1])\n\tby smtp3.osuosl.org (Postfix) with ESMTP id 0E872607F7;\n\tWed, 18 Feb 2026 10:13:33 +0000 (UTC)","from smtp3.osuosl.org ([127.0.0.1])\n by localhost (smtp3.osuosl.org [127.0.0.1]) (amavis, port 10024) with ESMTP\n id jmAP4IN7TZOs; Wed, 18 Feb 2026 10:13:32 +0000 (UTC)","from lists1.osuosl.org (lists1.osuosl.org [140.211.166.142])\n\tby smtp3.osuosl.org (Postfix) with ESMTP id 59254607F3;\n\tWed, 18 Feb 2026 10:13:32 +0000 (UTC)","from smtp3.osuosl.org (smtp3.osuosl.org [IPv6:2605:bc80:3010::136])\n by lists1.osuosl.org (Postfix) with ESMTP id 5C95C35B\n for ; Wed, 18 Feb 2026 10:13:26 +0000 (UTC)","from localhost (localhost [127.0.0.1])\n by smtp3.osuosl.org (Postfix) with ESMTP id 427B860785\n for ; Wed, 18 Feb 2026 10:13:26 +0000 (UTC)","from smtp3.osuosl.org ([127.0.0.1])\n by localhost (smtp3.osuosl.org [127.0.0.1]) (amavis, port 10024) with ESMTP\n id 552cRnftorNL for ;\n Wed, 18 Feb 2026 10:13:25 +0000 (UTC)","from sea.source.kernel.org (sea.source.kernel.org [172.234.252.31])\n by smtp3.osuosl.org (Postfix) with ESMTPS id 4BAE960726\n for ; Wed, 18 Feb 2026 10:13:25 +0000 (UTC)","from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58])\n by sea.source.kernel.org (Postfix) with ESMTP id 1258844524;\n Wed, 18 Feb 2026 10:13:25 +0000 (UTC)","by smtp.kernel.org (Postfix) with ESMTPSA id EA9A3C19425;\n Wed, 18 Feb 2026 10:13:24 +0000 (UTC)","from mchehab by mail.kernel.org with local (Exim 4.99.1)\n (envelope-from )\n id 1vseYd-00000000Lh8-0uUp; Wed, 18 Feb 2026 11:13:23 +0100"],"X-Virus-Scanned":["amavis at osuosl.org","amavis at osuosl.org"],"X-Comment":"SPF check N/A for local connections - client-ip=140.211.166.142;\n helo=lists1.osuosl.org; envelope-from=intel-wired-lan-bounces@osuosl.org;\n receiver= ","DKIM-Filter":["OpenDKIM Filter v2.11.0 smtp3.osuosl.org 59254607F3","OpenDKIM Filter v2.11.0 smtp3.osuosl.org 4BAE960726"],"DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed; d=osuosl.org;\n\ts=default; t=1771409612;\n\tbh=mTYLbojPpVFA2MVDjQ4fAyKVTvcXVuXTJx29E7yNHwE=;\n\th=From:To:Cc:Date:In-Reply-To:References:Subject:List-Id:\n\t List-Unsubscribe:List-Archive:List-Post:List-Help:List-Subscribe:\n\t From;\n\tb=MEkoqPNo3clA+GxqlMTLPsegTe0kBK4qBoed9+mkfkRucdP6cOfToDd+2jfl64udZ\n\t NQwS85pHvDuGkBeN4MxBNP+lCcEZnYltoREo7vXbbPTPoTY29VTaAVayELYfxYaYjg\n\t oMby2z8Vb44HXHFFlaeirmnQ/aPNoASTTUTZsYK9IPO5WFQQBRE9cReTFtCppSYzdJ\n\t iCRRokqr0iEo048ZiYA4xAbYKWbwYDiDSKH87inDvPYNmIpbtXvmvwCJkgZzUd9HDT\n\t o5s5zXvqBMCJLWzXqjHdsV8x+wS968LjLFdCLriF7uB1PUJ4uP7d8E3T6dobTJzoQU\n\t UaOX05XeDLVKg==","Received-SPF":"Pass (mailfrom) identity=mailfrom; client-ip=172.234.252.31;\n helo=sea.source.kernel.org; envelope-from=mchehab+huawei@kernel.org;\n receiver=","DMARC-Filter":"OpenDMARC Filter v1.4.2 smtp3.osuosl.org 4BAE960726","From":"Mauro Carvalho Chehab ","To":"Jonathan Corbet ,\n Linux Doc Mailing List ","Cc":"Mauro Carvalho Chehab ,\n intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org,\n linux-kernel@vger.kernel.org, netdev@vger.kernel.org,\n Aleksandr Loktionov ,\n Randy Dunlap ","Date":"Wed, 18 Feb 2026 11:12:49 +0100","Message-ID":"\n ","X-Mailer":"git-send-email 2.52.0","In-Reply-To":"","References":"","MIME-Version":"1.0","Content-Type":"text/plain; charset=\"utf-8\"","Content-Transfer-Encoding":"8bit","X-Mailman-Original-DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple;\n d=kernel.org; s=k20201202; t=1771409605;\n bh=DvfUwTuholX9BC+W38TUGNzdKlUVnreeYvd3PlaaCGM=;\n h=From:To:Cc:Subject:Date:In-Reply-To:References:From;\n b=IO/JRtRAZj1btQXAZYuHO3FVv0sk70uvJvDQTiS/kTA63xY5Fm5GuSVHCJT8NDuuG\n bFxwUfGH+yckZPM2PpqfmzCjcrepNSH3JP3ACwMoAO+3uW2AFEj7FBwzRA9Xqp9tYF\n eOWuyp6YYdywv1b2hvvYjsPetFFraFwl6Nq1MmI9UFaAi2g7qupBtB7so4ix5GF9lO\n rX6543ISqBAgQeCH2r0+H94CdsqE41uPfCHjDIDR9gspPNDokPgCbBtGSDcuxndtKQ\n Uy7l+up6Flmx3XdfdoxvEBmCFlxecMfDAdK8Z7CBwhNbA7BSqPG4KpLBOt0rYVvWA/\n L2oM/RY4AJpuw==","X-Mailman-Original-Authentication-Results":["smtp3.osuosl.org;\n dmarc=pass (p=quarantine dis=none)\n header.from=kernel.org","smtp3.osuosl.org;\n dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org\n header.a=rsa-sha256 header.s=k20201202 header.b=IO/JRtRA"],"Subject":"[Intel-wired-lan] [PATCH 19/38] docs: kdoc_re: make NestedMatch use\n KernRe","X-BeenThere":"intel-wired-lan@osuosl.org","X-Mailman-Version":"2.1.30","Precedence":"list","List-Id":"Intel Wired Ethernet Linux Kernel Driver Development\n ","List-Unsubscribe":",\n ","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n ","Errors-To":"intel-wired-lan-bounces@osuosl.org","Sender":"\"Intel-wired-lan\" "},"content":"Instead of using re_compile, let's create the class with the\nregex and use KernRe to keep it cached.\n\nSigned-off-by: Mauro Carvalho Chehab \nReviewed-by: Aleksandr Loktionov \n---\n tools/lib/python/kdoc/kdoc_parser.py | 55 ++++++++--------------------\n tools/lib/python/kdoc/kdoc_re.py | 24 ++++++++----\n 2 files changed, 33 insertions(+), 46 deletions(-)","diff":"diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py\nindex 3ee169b505d3..06a7af4bfa57 100644\n--- a/tools/lib/python/kdoc/kdoc_parser.py\n+++ b/tools/lib/python/kdoc/kdoc_parser.py\n@@ -153,32 +153,7 @@ struct_xforms = [\n (KernRe(r'DEFINE_DMA_UNMAP_ADDR\\s*\\(' + struct_args_pattern + r'\\)', re.S), r'dma_addr_t \\1'),\n (KernRe(r'DEFINE_DMA_UNMAP_LEN\\s*\\(' + struct_args_pattern + r'\\)', re.S), r'__u32 \\1'),\n (KernRe(r'VIRTIO_DECLARE_FEATURES\\(([\\w_]+)\\)'), r'union { u64 \\1; u64 \\1_array[VIRTIO_FEATURES_U64S]; }'),\n-]\n-#\n-# Struct regexes here are guaranteed to have the end delimiter matching\n-# the start delimiter. Yet, right now, only one replace group\n-# is allowed.\n-#\n-struct_nested_prefixes = [\n- (re.compile(r'\\bSTRUCT_GROUP\\('), r'\\0'),\n-]\n-\n-#\n-# Function Regexes here are guaranteed to have the end delimiter matching\n-# the start delimiter.\n-#\n-function_nested_prefixes = [\n- (re.compile(r\"__cond_acquires\\s*\\(\"), \"\"),\n- (re.compile(r\"__cond_releases\\s*\\(\"), \"\"),\n- (re.compile(r\"__acquires\\s*\\(\"), \"\"),\n- (re.compile(r\"__releases\\s*\\(\"), \"\"),\n- (re.compile(r\"__must_hold\\s*\\(\"), \"\"),\n- (re.compile(r\"__must_not_hold\\s*\\(\"), \"\"),\n- (re.compile(r\"__must_hold_shared\\s*\\(\"), \"\"),\n- (re.compile(r\"__cond_acquires_shared\\s*\\(\"), \"\"),\n- (re.compile(r\"__acquires_shared\\s*\\(\"), \"\"),\n- (re.compile(r\"__releases_shared\\s*\\(\"), \"\"),\n- (re.compile(r\"__attribute__\\s*\\(\"), \"\"),\n+ (NestedMatch(r'\\bSTRUCT_GROUP\\('), r'\\0'),\n ]\n \n #\n@@ -211,6 +186,17 @@ function_xforms = [\n (KernRe(r\"DECL_BUCKET_PARAMS\\s*\\(\\s*(\\S+)\\s*,\\s*(\\S+)\\s*\\)\"), r\"\\1, \\2\"),\n (KernRe(r\"__no_context_analysis\\s*\"), \"\"),\n (KernRe(r\"__attribute_const__ +\"), \"\"),\n+ (NestedMatch(r\"__cond_acquires\\s*\\(\"), \"\"),\n+ (NestedMatch(r\"__cond_releases\\s*\\(\"), \"\"),\n+ (NestedMatch(r\"__acquires\\s*\\(\"), \"\"),\n+ (NestedMatch(r\"__releases\\s*\\(\"), \"\"),\n+ (NestedMatch(r\"__must_hold\\s*\\(\"), \"\"),\n+ (NestedMatch(r\"__must_not_hold\\s*\\(\"), \"\"),\n+ (NestedMatch(r\"__must_hold_shared\\s*\\(\"), \"\"),\n+ (NestedMatch(r\"__cond_acquires_shared\\s*\\(\"), \"\"),\n+ (NestedMatch(r\"__acquires_shared\\s*\\(\"), \"\"),\n+ (NestedMatch(r\"__releases_shared\\s*\\(\"), \"\"),\n+ (NestedMatch(r\"__attribute__\\s*\\(\"), \"\"),\n ]\n \n #\n@@ -231,7 +217,6 @@ var_xforms = [\n # Ancillary functions\n #\n \n-\n multi_space = KernRe(r'\\s\\s+')\n def trim_whitespace(s):\n \"\"\"\n@@ -425,8 +410,6 @@ class KernelDoc:\n # Place all potential outputs into an array\n self.entries = []\n \n- self.nested = NestedMatch()\n-\n #\n # We need Python 3.7 for its \"dicts remember the insertion\n # order\" guarantee\n@@ -524,14 +507,11 @@ class KernelDoc:\n # State flags\n self.state = state.NORMAL\n \n- def apply_transforms(self, regex_xforms, nested_xforms, text):\n+ def apply_transforms(self, xforms, text):\n \"\"\"Apply a set of transforms to a block of text.\"\"\"\n- for search, subst in regex_xforms:\n+ for search, subst in xforms:\n text = search.sub(subst, text)\n \n- for search, sub in nested_xforms:\n- text = self.nested.sub(search, sub, text)\n-\n return text.strip()\n \n def push_parameter(self, ln, decl_type, param, dtype,\n@@ -910,8 +890,7 @@ class KernelDoc:\n # Go through the list of members applying all of our transformations.\n #\n members = trim_private_members(members)\n- members = self.apply_transforms(struct_xforms, struct_nested_prefixes,\n- members)\n+ members = self.apply_transforms(struct_xforms, members)\n \n #\n # Deal with embedded struct and union members, and drop enums entirely.\n@@ -1126,9 +1105,7 @@ class KernelDoc:\n #\n # Apply the initial transformations.\n #\n- prototype = self.apply_transforms(function_xforms,\n- function_nested_prefixes,\n- prototype)\n+ prototype = self.apply_transforms(function_xforms, prototype)\n \n # Yes, this truly is vile. We are looking for:\n # 1. Return type (may be nothing if we're looking at a macro)\ndiff --git a/tools/lib/python/kdoc/kdoc_re.py b/tools/lib/python/kdoc/kdoc_re.py\nindex 2d83b6fb1cd6..fed9894a5c71 100644\n--- a/tools/lib/python/kdoc/kdoc_re.py\n+++ b/tools/lib/python/kdoc/kdoc_re.py\n@@ -200,7 +200,10 @@ class NestedMatch:\n #\n # FOO(arg1, arg2, arg3)\n \n- def _search(self, regex, line):\n+ def __init__(self, regex):\n+ self.regex = KernRe(regex)\n+\n+ def _search(self, line):\n \"\"\"\n Finds paired blocks for a regex that ends with a delimiter.\n \n@@ -222,7 +225,7 @@ class NestedMatch:\n \n stack = []\n \n- for match_re in regex.finditer(line):\n+ for match_re in self.regex.finditer(line):\n start = match_re.start()\n offset = match_re.end()\n string_char = None\n@@ -270,7 +273,7 @@ class NestedMatch:\n yield start, offset, pos + 1\n break\n \n- def search(self, regex, line):\n+ def search(self, line):\n \"\"\"\n This is similar to re.search:\n \n@@ -278,12 +281,12 @@ class NestedMatch:\n returning occurrences only if all delimiters are paired.\n \"\"\"\n \n- for t in self._search(regex, line):\n+ for t in self._search(line):\n \n yield line[t[0]:t[2]]\n \n- def sub(self, regex, sub, line, count=0):\n- r\"\"\"\n+ def sub(self, sub, line, count=0):\n+ \"\"\"\n This is similar to re.sub:\n \n It matches a regex that it is followed by a delimiter,\n@@ -304,7 +307,7 @@ class NestedMatch:\n cur_pos = 0\n n = 0\n \n- for start, end, pos in self._search(regex, line):\n+ for start, end, pos in self._search(line):\n out += line[cur_pos:start]\n \n # Value, ignoring start/end delimiters\n@@ -331,3 +334,10 @@ class NestedMatch:\n out += line[cur_pos:l]\n \n return out\n+\n+ def __repr__(self):\n+ \"\"\"\n+ Returns a displayable version of the class init.\n+ \"\"\"\n+\n+ return f'NestedMatch(\"{self.regex.regex.pattern}\")'\n","prefixes":["19/38"]}