{"id":2197657,"url":"http://patchwork.ozlabs.org/api/1.0/patches/2197657/?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:35","name":"[05/38] docs: kdoc_parser: add functions support for NestedMatch","commit_ref":null,"pull_url":null,"state":"handled-elsewhere","archived":false,"hash":"97d8996b95d5cde8f47cd27b7f645e1e8a69b475","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/dc810d3456e95f0c27bbf5808c1c03b51612ea7e.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/2197657/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=lBkUmK3E;\n\tdkim-atps=neutral","legolas.ozlabs.org;\n spf=pass (sender SPF authorized) smtp.mailfrom=osuosl.org\n (client-ip=2605:bc80:3010::138; helo=smtp1.osuosl.org;\n envelope-from=intel-wired-lan-bounces@osuosl.org;\n receiver=patchwork.ozlabs.org)"],"Received":["from smtp1.osuosl.org (smtp1.osuosl.org [IPv6:2605:bc80:3010::138])\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 4fGC5T2w7qz1xwr\n\tfor ; Wed, 18 Feb 2026 21:13:33 +1100 (AEDT)","from localhost (localhost [127.0.0.1])\n\tby smtp1.osuosl.org (Postfix) with ESMTP id F052B8109E;\n\tWed, 18 Feb 2026 10:13:29 +0000 (UTC)","from smtp1.osuosl.org ([127.0.0.1])\n by localhost (smtp1.osuosl.org [127.0.0.1]) (amavis, port 10024) with ESMTP\n id 9EsnPfhEQCB1; Wed, 18 Feb 2026 10:13:29 +0000 (UTC)","from lists1.osuosl.org (lists1.osuosl.org [140.211.166.142])\n\tby smtp1.osuosl.org (Postfix) with ESMTP id 5AA4E810A1;\n\tWed, 18 Feb 2026 10:13:29 +0000 (UTC)","from smtp3.osuosl.org (smtp3.osuosl.org [IPv6:2605:bc80:3010::136])\n by lists1.osuosl.org (Postfix) with ESMTP id 2E43435B\n for ; Wed, 18 Feb 2026 10:13:24 +0000 (UTC)","from localhost (localhost [127.0.0.1])\n by smtp3.osuosl.org (Postfix) with ESMTP id E1C8E60600\n for ; Wed, 18 Feb 2026 10:13:22 +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 2FWlXhgLliAj for ;\n Wed, 18 Feb 2026 10:13:20 +0000 (UTC)","from sea.source.kernel.org (sea.source.kernel.org\n [IPv6:2600:3c0a:e001:78e:0:1991:8:25])\n by smtp3.osuosl.org (Postfix) with ESMTPS id 2BCC3605E6\n for ; Wed, 18 Feb 2026 10:13:20 +0000 (UTC)","from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58])\n by sea.source.kernel.org (Postfix) with ESMTP id DA8E944579;\n Wed, 18 Feb 2026 10:13:19 +0000 (UTC)","by smtp.kernel.org (Postfix) with ESMTPSA id BD02CC19423;\n Wed, 18 Feb 2026 10:13:19 +0000 (UTC)","from mchehab by mail.kernel.org with local (Exim 4.99.1)\n (envelope-from )\n id 1vseYX-00000000LPj-33OO; Wed, 18 Feb 2026 11:13:17 +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 smtp1.osuosl.org 5AA4E810A1","OpenDKIM Filter v2.11.0 smtp3.osuosl.org 2BCC3605E6"],"DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed; d=osuosl.org;\n\ts=default; t=1771409609;\n\tbh=OTrRAyK+tvI2qbstcRoXk0n6cc7Rik1oLG/+OrJw+44=;\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=lBkUmK3EdWKIAJNRAob6rPxvMUdmRWJUsnkamgGzclCLNUk0TgCP2YFmTohYJdh1U\n\t Ep+t5ZHpB5m+8V6YWP13k28bKunRkUEaIaNUB+S9CFGiFV8/IYPnt3tzeHJoNv+m15\n\t nLl2DbWGdpfurL4zKqM36YLQf6GjW8ADr2ptM7cPsmUnwgXuhssJ1hJNbp6rOvDAG9\n\t PtXk2FvoBvixNJEjlzoHwhIiNUquseP9DiWEGQFg8bTZ46whumzbiD17W0Ikf7mN7u\n\t 0zjUaG9FvikSyQ8K+28JmN5Iu0Ka5vx6MkS68UOvG4AuuASfHVUy2MV1LRaiiM2FE2\n\t Idh0g8eG0GwJg==","Received-SPF":"Pass (mailfrom) identity=mailfrom;\n client-ip=2600:3c0a:e001:78e:0:1991:8:25; helo=sea.source.kernel.org;\n envelope-from=mchehab+huawei@kernel.org; receiver=","DMARC-Filter":"OpenDMARC Filter v1.4.2 smtp3.osuosl.org 2BCC3605E6","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:35 +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=1771409599;\n bh=M0qmGyr3HuNHtOM507wR/t90o2hFNZdaNjjz4CqTCCI=;\n h=From:To:Cc:Subject:Date:In-Reply-To:References:From;\n b=bKn4Oc/bLsrS78n59qVcKj73TULTq/pLvB9eYi6SIqFgK/GXfjPPQ+oXWolwyFERD\n i8XPBpMogcpEBPp128ppIWlBEADNV+r2ITpQGhV72TZhd2JuxKhsd0YL0VHvy7zWtk\n NKr1H/0L9hkduGt+zYBiI+XoH1c36Mkcf0IIAPfqFOywdR514o7mLnd/lm2Z6m+LnN\n laxzwtVXo5KxE97Q5mKYgBakE1VEbW78DOx/it21E2FSrz8/9SQUk3EeXxu93TqKiK\n GlAFQyu9bR5ruRU7t5RT9ancwzYgPPJIG6HRZhAb+Wo0Z9QqBIssHLrIQafarn57Rl\n b7nRVg4YlnKDA==","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=bKn4Oc/b"],"Subject":"[Intel-wired-lan] [PATCH 05/38] docs: kdoc_parser: add functions\n support for NestedMatch","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":"Some annotations macros may have nested parenthesis, causing normal\nregex parsing to fail.\n\nExtend apply_transforms to also use NestedMatch and add support\nfor nested functions.\n\nSigned-off-by: Mauro Carvalho Chehab \nAcked-by: Randy Dunlap \nTested-by: Randy Dunlap \nReviewed-by: Aleksandr Loktionov \n---\n tools/lib/python/kdoc/kdoc_parser.py | 38 ++++++++++++++++++----------\n 1 file changed, 25 insertions(+), 13 deletions(-)","diff":"diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py\nindex 9643ffb7584a..af0ab732048b 100644\n--- a/tools/lib/python/kdoc/kdoc_parser.py\n+++ b/tools/lib/python/kdoc/kdoc_parser.py\n@@ -152,7 +152,7 @@ struct_xforms = [\n (KernRe(r'DEFINE_DMA_UNMAP_LEN\\s*\\(' + struct_args_pattern + r'\\)', re.S), r'__u32 \\1'),\n ]\n #\n-# Regexes here are guaranteed to have the end delimiter matching\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@@ -160,6 +160,13 @@ struct_nested_prefixes = [\n (re.compile(r'\\bSTRUCT_GROUP\\('), r'\\1'),\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+]\n+\n #\n # Transforms for function prototypes\n #\n@@ -208,13 +215,6 @@ var_xforms = [\n # Ancillary functions\n #\n \n-def apply_transforms(xforms, text):\n- \"\"\"\n- Apply a set of transforms to a block of text.\n- \"\"\"\n- for search, subst in xforms:\n- text = search.sub(subst, text)\n- return text\n \n multi_space = KernRe(r'\\s\\s+')\n def trim_whitespace(s):\n@@ -409,6 +409,8 @@ 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@@ -506,6 +508,16 @@ class KernelDoc:\n # State flags\n self.state = state.NORMAL\n \n+ def apply_transforms(self, regex_xforms, nested_xforms, text):\n+ \"\"\"Apply a set of transforms to a block of text.\"\"\"\n+ for search, subst in regex_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 org_arg, declaration_name):\n \"\"\"\n@@ -882,11 +894,9 @@ class KernelDoc:\n # Go through the list of members applying all of our transformations.\n #\n members = trim_private_members(members)\n- members = apply_transforms(struct_xforms, members)\n+ members = self.apply_transforms(struct_xforms, struct_nested_prefixes,\n+ members)\n \n- nested = NestedMatch()\n- for search, sub in struct_nested_prefixes:\n- members = nested.sub(search, sub, members)\n #\n # Deal with embedded struct and union members, and drop enums entirely.\n #\n@@ -1089,7 +1099,9 @@ class KernelDoc:\n #\n # Apply the initial transformations.\n #\n- prototype = apply_transforms(function_xforms, prototype)\n+ prototype = self.apply_transforms(function_xforms,\n+ function_nested_prefixes,\n+ 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)\n","prefixes":["05/38"]}