From nobody Sun Oct 5 16:20:38 2025 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 91A533C17; Fri, 1 Aug 2025 00:13:41 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754007223; cv=none; b=VupCa2UUU7hRra6JUnIP7lS0d6q1OLD1iHaISJeaxfBhq7TTi5SVod/oPDyhS8L3E6h5fEpNWIam9c0C5gBWwNOIhLh8kO4NOC76DtII80u0MHjZN0jon7/kTiEa2bJudDOp1mCH+GkDurRaCqUDgZe5uUIf8/drPTRoizkxFCE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754007223; c=relaxed/simple; bh=WW1zK6X21lvMsWf5X/dyje1CjqFwmnQ4wIE57rzG/jU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=OiPNEa3c6uAvSyO58lWhVEMNooJQG6M2MiDFTr104RF6xZIpW0o2vMoaYUVX7+b7g4c2Q5m9ca0hdGPm4PLqPraYEgUtXdZxZIToMELcfbHDQ370JC6BA/eYbDi4aPdxWhSBNybMkEsnbJw7wfATNDBVP0xq9JYWvvF/FW7qKps= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=rpXoYbcg; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="rpXoYbcg" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 3265840ADD DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1754007215; bh=bAJMNiUlM1zaOfKybMz1uucAVs1vtJChh2CsSykFci4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=rpXoYbcguW8yUdKyjphyrDMp93I655rd5yyc959d9GrOP4LKj80F+USfC/AvvSd9l woJgkqQ/Tp59aZwA0/Br8ZsdKRPZ5vbs7Oh7NLDNFCMrXUdQDoGvbOk/qVLM37taRy WCX9W2V1baTTt7x6qdiXBDzu3u9p0nmRYmIZ88gUZA2ReaXLzpCCm+sbuNKQ75fFv/ FjBmHgeoyneG3M1rkv0qxh8qCNHn9+uUcouGObu9mnbeSnCWIFCJDgUTM1n1Zs47T0 v/l7ddXahPDvI+eVyL7HhbzZhhitAttrO9nXh1RQJlkL7/44Dg+6XxfG0cqdLI39Tl jGHXAmwlBaJHQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 3265840ADD; Fri, 1 Aug 2025 00:13:35 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 01/12] docs: kdoc: consolidate the stripping of private struct/union members Date: Thu, 31 Jul 2025 18:13:15 -0600 Message-ID: <20250801001326.924276-2-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250801001326.924276-1-corbet@lwn.net> References: <20250801001326.924276-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" There were two locations duplicating the logic of stripping private members and associated comments; coalesce them into one, and add some comments describing what's going on. Output change: we now no longer add extraneous white space around macro definitions. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 40 ++++++++++++++++++--------------- 1 file changed, 22 insertions(+), 18 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index c3fe4bd5eab4..93fcd8807aa8 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -81,6 +81,21 @@ multi_space =3D KernRe(r'\s\s+') def trim_whitespace(s): return multi_space.sub(' ', s.strip()) =20 +# +# Remove struct/enum members that have been marked "private". +# +def trim_private_members(text): + # + # First look for a "public:" block that ends a private region, then + # handle the "private until the end" case. + # + text =3D KernRe(r'/\*\s*private:.*?/\*\s*public:.*?\*/', flags=3Dre.S)= .sub('', text) + text =3D KernRe(r'/\*\s*private:.*', flags=3Dre.S).sub('', text) + # + # We needed the comments to do the above, but now we can take them out. + # + return KernRe(r'\s*/\*.*?\*/\s*', flags=3Dre.S).sub('', text).strip() + class state: """ State machine enums @@ -568,12 +583,6 @@ class KernelDoc: args_pattern =3D r'([^,)]+)' =20 sub_prefixes =3D [ - (KernRe(r'\/\*\s*private:.*?\/\*\s*public:.*?\*\/', re.S | re.= I), ''), - (KernRe(r'\/\*\s*private:.*', re.S | re.I), ''), - - # Strip comments - (KernRe(r'\/\*.*?\*\/', re.S), ''), - # Strip attributes (attribute, ' '), (KernRe(r'\s*__aligned\s*\([^;]*\)', re.S), ' '), @@ -648,6 +657,7 @@ class KernelDoc: (re.compile(r'\bSTRUCT_GROUP\('), r'\1'), ] =20 + members =3D trim_private_members(members) for search, sub in sub_prefixes: members =3D search.sub(sub, members) =20 @@ -797,24 +807,18 @@ class KernelDoc: """ Stores an enum inside self.entries array. """ - - # Ignore members marked private - proto =3D KernRe(r'\/\*\s*private:.*?\/\*\s*public:.*?\*\/', flags= =3Dre.S).sub('', proto) - proto =3D KernRe(r'\/\*\s*private:.*}', flags=3Dre.S).sub('}', pro= to) - - # Strip comments - proto =3D KernRe(r'\/\*.*?\*\/', flags=3Dre.S).sub('', proto) - - # Strip #define macros inside enums + # + # Strip preprocessor directives. Note that this depends on the + # trailing semicolon we added in process_proto_type(). + # proto =3D KernRe(r'#\s*((define|ifdef|if)\s+|endif)[^;]*;', flags= =3Dre.S).sub('', proto) - # # Parse out the name and members of the enum. Typedef form first. # r =3D KernRe(r'typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;') if r.search(proto): declaration_name =3D r.group(2) - members =3D r.group(1).rstrip() + members =3D trim_private_members(r.group(1)) # # Failing that, look for a straight enum # @@ -822,7 +826,7 @@ class KernelDoc: r =3D KernRe(r'enum\s+(\w*)\s*\{(.*)\}') if r.match(proto): declaration_name =3D r.group(1) - members =3D r.group(2).rstrip() + members =3D trim_private_members(r.group(2)) # # OK, this isn't going to work. # --=20 2.50.1 From nobody Sun Oct 5 16:20:38 2025 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 54E113FFD; Fri, 1 Aug 2025 00:13:42 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754007224; cv=none; b=fnF4tIiOd1G0n8DweZI050fBc6rJD08MIrREPozigqdbWqblnJjPjzqWI3wscUKs4fVcT17ppZ6atHsXji00zwIt/9nqwD17UaH0XQFDncO/6ciK086zklCLz9GVMCgLyvoBMzCd9/aFAYjEKh/7yKFAzE12uyrSc/CoXnQITs8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754007224; c=relaxed/simple; bh=blEVpsi6veADUr0KfDdwggA32HbZDYZqLsP2P50MwYY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=R61MztTMSLUVOMJC8VVCwQyY4U9dXZaE0BeCiwy2yrMvAABdD/HCiW0urYbmQy6EvyRPg+C76VUhPDFnSIaCP0KmCxziM1wGEwWeNHYo+ppd1a33/zIYPKt5oWLvY/j7XUA398/u1wWyIE0dJJi0Jgt8zqKoUUzz0GuXTkJQMDc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=HBi64n7u; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="HBi64n7u" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net B640A40AE4 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1754007216; bh=IuPz8fhYbCvGgUOKEXCuX26f3cOrt2ePp/b91/+1Mmw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=HBi64n7uwabgrYR1nhWv/mYdLLM04xkz3N9JgdD1tChXzbMn5IX7LE4rjoYXVdU/9 a7BcqpDHsc2E8UyT12ry3EtenqvCjERhU29Pi78OQ2ogeFuUjaRtmtsvi5nR9G8wSP rsK/ilGcNoU/YfH4Q36stZ5jT4W90wPavkvbKwGPIA83huOMnRdagANd1pC7QZuOVx /ieErMM8LwtD+uu91/frpau0VgDFC1U3JT2FJ7k2YF0nKUHYRzRhbcm9pNMZECjb1E p3kmc13j0kuyXhMmvsFe1vIVmZS6C8TVrl55a+BVbq1Ez4cz0EdYntgs7U4PiSMKeb PWLD9D5v3w1yg== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id B640A40AE4; Fri, 1 Aug 2025 00:13:35 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 02/12] docs: kdoc: Move a regex line in dump_struct() Date: Thu, 31 Jul 2025 18:13:16 -0600 Message-ID: <20250801001326.924276-3-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250801001326.924276-1-corbet@lwn.net> References: <20250801001326.924276-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" The complex struct_members regex was defined far from its use; bring the two together. Remove some extraneous backslashes while making the move. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 93fcd8807aa8..9948ede739a5 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -551,7 +551,6 @@ class KernelDoc: ] =20 definition_body =3D r'\{(.*)\}\s*' + "(?:" + '|'.join(qualifiers) = + ")?" - struct_members =3D KernRe(type_pattern + r'([^\{\};]+)(\{)([^\{\}]= *)(\})([^\{\}\;]*)(\;)') =20 # Extract struct/union definition members =3D None @@ -683,6 +682,7 @@ class KernelDoc: # So, we need to have an extra loop on Python to override such # re limitation. =20 + struct_members =3D KernRe(type_pattern + r'([^{};]+)(\{)([^{}]*)(\= })([^{};]*)(;)') while True: tuples =3D struct_members.findall(members) if not tuples: --=20 2.50.1 From nobody Sun Oct 5 16:20:38 2025 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 54DDF3D81; Fri, 1 Aug 2025 00:13:42 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754007224; cv=none; b=eAd+FjeUb48gk3wLvRxld2d0tX5DgUgZdxWDi8M6o+W+7Q7mb5+UVChabsAVQ7zbNeDmoNaOS4ukc2A3xrf1wmVhKU5vO/iFrJ7aOQeMTi46Fa4oeFU0KRmTwDUClDWSghcqwqGnBY6xXkACn88HqwHDLMrHQ99HvGPE7VlYT8Y= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754007224; c=relaxed/simple; bh=bEcraGPV3gR6r987wiaDaKSp3nJiNG59kH23+FTy4qk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=kH8CuPFFeP8awQybEvWoCGVL5RNaMR6LwCOWMrVsmGGVzxWrJI2WP2KAW3+xbiaSmFL+54ZbTvODEwJEks9MnGjd9vOrfJB+MQucv6nw81voZ8d5CadGz4FCRv0nAGxXLsspug5FyOpljl9xHb3DVVrMWffytJqRXbOKo89S3RY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=emE1SCB3; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="emE1SCB3" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 4CD5F40AE5 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1754007216; bh=BMowMrRpgTtdnzeANz/44PHHl5NAaWPnyULE2WLjzW0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=emE1SCB3Je0HVXYzD3QL1p5c9SgjuyoubV3LnMmAyeGbdcfHAMcQcu9Q7BlhQnVFs W35Y6sflAxcFqVhRNJv1BmbuT6VIIqSSymahfHws1HjHJ9AtiNdrdRDkJ7juyXecnB e6JV3cc+zGG8xUaXPK/Q00vigjv2y3qEUClqIoez6h2X1LF/IYiUwsrIXF94sEZd+j Im4qr7SEUDQ01/2ySAyzXZmND+nfpxxoI/j9KId2BqXfeUC0f9j2ddihCK9jLu7xGq +MXpLXR2///xWwhprQaRRp0a404TtsZEfwdG7vh0XIwdHah3cLxH33DnJ4iyp3wHOk mhDLNY0RUrmRA== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 4CD5F40AE5; Fri, 1 Aug 2025 00:13:36 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 03/12] docs: kdoc: backslashectomy in kdoc_parser Date: Thu, 31 Jul 2025 18:13:17 -0600 Message-ID: <20250801001326.924276-4-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250801001326.924276-1-corbet@lwn.net> References: <20250801001326.924276-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" A lot of the regular expressions in this file have extraneous backslashes that may have been needed in Perl, but aren't helpful here. Take them out to reduce slightly the visual noise. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 40 ++++++++++++++++----------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 9948ede739a5..e1efa65a3480 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -46,7 +46,7 @@ doc_decl =3D doc_com + KernRe(r'(\w+)', cache=3DFalse) known_section_names =3D 'description|context|returns?|notes?|examples?' known_sections =3D KernRe(known_section_names, flags =3D re.I) doc_sect =3D doc_com + \ - KernRe(r'\s*(\@[.\w]+|\@\.\.\.|' + known_section_names + r')\s*:([^:].= *)?$', + KernRe(r'\s*(@[.\w]+|@\.\.\.|' + known_section_names + r')\s*:([^:].*)= ?$', flags=3Dre.I, cache=3DFalse) =20 doc_content =3D doc_com_body + KernRe(r'(.*)', cache=3DFalse) @@ -60,7 +60,7 @@ attribute =3D KernRe(r"__attribute__\s*\(\([a-z0-9,_\*\s\= (\)]*\)\)", export_symbol =3D KernRe(r'^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*',= cache=3DFalse) export_symbol_ns =3D KernRe(r'^\s*EXPORT_SYMBOL_NS(_GPL)?\s*\(\s*(\w+)\s*,= \s*"\S+"\)\s*', cache=3DFalse) =20 -type_param =3D KernRe(r"\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)", cache=3DFalse) +type_param =3D KernRe(r"@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)", cache=3DFalse) =20 # # Tests for the beginning of a kerneldoc block in its various forms. @@ -331,7 +331,7 @@ class KernelDoc: =20 self.entry.anon_struct_union =3D False =20 - param =3D KernRe(r'[\[\)].*').sub('', param, count=3D1) + param =3D KernRe(r'[)[].*').sub('', param, count=3D1) =20 if dtype =3D=3D "" and param.endswith("..."): if KernRe(r'\w\.\.\.$').search(param): @@ -405,7 +405,7 @@ class KernelDoc: =20 for arg in args.split(splitter): # Strip comments - arg =3D KernRe(r'\/\*.*\*\/').sub('', arg) + arg =3D KernRe(r'/\*.*\*/').sub('', arg) =20 # Ignore argument attributes arg =3D KernRe(r'\sPOS0?\s').sub(' ', arg) @@ -428,14 +428,14 @@ class KernelDoc: =20 arg =3D arg.replace('#', ',') =20 - r =3D KernRe(r'[^\(]+\(\*?\s*([\w\[\]\.]*)\s*\)') + r =3D KernRe(r'[^(]+\(\*?\s*([\w[\].]*)\s*\)') if r.match(arg): param =3D r.group(1) else: self.emit_msg(ln, f"Invalid param: {arg}") param =3D arg =20 - dtype =3D KernRe(r'([^\(]+\(\*?)\s*' + re.escape(param)).s= ub(r'\1', arg) + dtype =3D KernRe(r'([^(]+\(\*?)\s*' + re.escape(param)).su= b(r'\1', arg) self.push_parameter(ln, decl_type, param, dtype, arg, declaration_name) =20 @@ -443,14 +443,14 @@ class KernelDoc: # Array-of-pointers =20 arg =3D arg.replace('#', ',') - r =3D KernRe(r'[^\(]+\(\s*\*\s*([\w\[\]\.]*?)\s*(\s*\[\s*[= \w]+\s*\]\s*)*\)') + r =3D KernRe(r'[^(]+\(\s*\*\s*([\w[\].]*?)\s*(\s*\[\s*[\w]= +\s*\]\s*)*\)') if r.match(arg): param =3D r.group(1) else: self.emit_msg(ln, f"Invalid param: {arg}") param =3D arg =20 - dtype =3D KernRe(r'([^\(]+\(\*?)\s*' + re.escape(param)).s= ub(r'\1', arg) + dtype =3D KernRe(r'([^(]+\(\*?)\s*' + re.escape(param)).su= b(r'\1', arg) =20 self.push_parameter(ln, decl_type, param, dtype, arg, declaration_name) @@ -637,8 +637,8 @@ class KernelDoc: # it is better to also move those to the NestedMatch logic, # to ensure that parenthesis will be properly matched. =20 - (KernRe(r'__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)', re= .S), r'DECLARE_BITMAP(\1, __ETHTOOL_LINK_MODE_MASK_NBITS)'), - (KernRe(r'DECLARE_PHY_INTERFACE_MASK\s*\(([^\)]+)\)', re.S), r= 'DECLARE_BITMAP(\1, PHY_INTERFACE_MODE_MAX)'), + (KernRe(r'__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^)]+)\)', re.= S), r'DECLARE_BITMAP(\1, __ETHTOOL_LINK_MODE_MASK_NBITS)'), + (KernRe(r'DECLARE_PHY_INTERFACE_MASK\s*\(([^)]+)\)', re.S), r'= DECLARE_BITMAP(\1, PHY_INTERFACE_MODE_MAX)'), (KernRe(r'DECLARE_BITMAP\s*\(' + args_pattern + r',\s*' + args= _pattern + r'\)', re.S), r'unsigned long \1[BITS_TO_LONGS(\2)]'), (KernRe(r'DECLARE_HASHTABLE\s*\(' + args_pattern + r',\s*' + a= rgs_pattern + r'\)', re.S), r'unsigned long \1[1 << ((\2) - 1)]'), (KernRe(r'DECLARE_KFIFO\s*\(' + args_pattern + r',\s*' + args_= pattern + r',\s*' + args_pattern + r'\)', re.S), r'\2 *\1'), @@ -700,7 +700,7 @@ class KernelDoc: s_id =3D s_id.strip() =20 newmember +=3D f"{maintype} {s_id}; " - s_id =3D KernRe(r'[:\[].*').sub('', s_id) + s_id =3D KernRe(r'[:[].*').sub('', s_id) s_id =3D KernRe(r'^\s*\**(\S+)\s*').sub(r'\1', s_id) =20 for arg in content.split(';'): @@ -709,7 +709,7 @@ class KernelDoc: if not arg: continue =20 - r =3D KernRe(r'^([^\(]+\(\*?\s*)([\w\.]*)(\s*\).*)= ') + r =3D KernRe(r'^([^(]+\(\*?\s*)([\w.]*)(\s*\).*)') if r.match(arg): # Pointer-to-function dtype =3D r.group(1) @@ -767,12 +767,12 @@ class KernelDoc: self.check_sections(ln, declaration_name, decl_type) =20 # Adjust declaration for better display - declaration =3D KernRe(r'([\{;])').sub(r'\1\n', declaration) + declaration =3D KernRe(r'([{;])').sub(r'\1\n', declaration) declaration =3D KernRe(r'\}\s+;').sub('};', declaration) =20 # Better handle inlined enums while True: - r =3D KernRe(r'(enum\s+\{[^\}]+),([^\n])') + r =3D KernRe(r'(enum\s+\{[^}]+),([^\n])') if not r.search(declaration): break =20 @@ -969,8 +969,8 @@ class KernelDoc: # - pci_match_device, __copy_to_user (long return type) =20 name =3D r'[a-zA-Z0-9_~:]+' - prototype_end1 =3D r'[^\(]*' - prototype_end2 =3D r'[^\{]*' + prototype_end1 =3D r'[^(]*' + prototype_end2 =3D r'[^{]*' prototype_end =3D fr'\(({prototype_end1}|{prototype_end2})\)' =20 # Besides compiling, Perl qr{[\w\s]+} works as a non-capturing gro= up. @@ -1044,7 +1044,7 @@ class KernelDoc: Stores a typedef inside self.entries array. """ =20 - typedef_type =3D r'((?:\s+[\w\*]+\b){0,7}\s+(?:\w+\b|\*+))\s*' + typedef_type =3D r'((?:\s+[\w*]+\b){0,7}\s+(?:\w+\b|\*+))\s*' typedef_ident =3D r'\*?\s*(\w\S+)\s*' typedef_args =3D r'\s*\((.*)\);' =20 @@ -1265,7 +1265,7 @@ class KernelDoc: self.dump_section() =20 # Look for doc_com + + doc_end: - r =3D KernRe(r'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') + r =3D KernRe(r'\s*\*\s*[a-zA-Z_0-9:.]+\*/') if r.match(line): self.emit_msg(ln, f"suspicious ending line: {line}") =20 @@ -1476,14 +1476,14 @@ class KernelDoc: """Ancillary routine to process a function prototype""" =20 # strip C99-style comments to end of line - line =3D KernRe(r"\/\/.*$", re.S).sub('', line) + line =3D KernRe(r"//.*$", re.S).sub('', line) # # Soak up the line's worth of prototype text, stopping at { or ; i= f present. # if KernRe(r'\s*#\s*define').match(line): self.entry.prototype =3D line elif not line.startswith('#'): # skip other preprocessor stuff - r =3D KernRe(r'([^\{]*)') + r =3D KernRe(r'([^{]*)') if r.match(line): self.entry.prototype +=3D r.group(1) + " " # --=20 2.50.1 From nobody Sun Oct 5 16:20:38 2025 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 7A01D8F6F; Fri, 1 Aug 2025 00:13:43 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754007226; cv=none; b=MCrpeVx99jkyMDh77SusxsxXvC8ZqF6jLhKf5h0+FrzmEFao/vQIJep7+dFXcK+xZ7+wDo4To2xSm8QKgRvuWyJL0KJbCtEXaW9qWmW3YXE0keLCsniuEir+pRh9t0J7KN7B2XENk5nIrT7wnFFFmTLPRs4feZfWUTkOyd4bNF8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754007226; c=relaxed/simple; bh=QHY5CU7DPP4vg/fuxV4AfA5GvYFe49NXylWjF6I+0eU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=SMzw19pKepQhfGwQBYpNrDWKXhlCL4EI4iEy3GrBYTl/ZY7HASEKcouu0rV0eZgFZwELv5WTOldrEnD06cVcHAIbLjSMi6u9HBxfsbZ7MvmXaWdoJGe/bO2MZeH7YJL+6PCeD4zScN/ZIeU1GPM4KbCoPGj5tcS1qn3Mb55s0tY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=Af4DUZAQ; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="Af4DUZAQ" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net D1AAF40AE9 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1754007217; bh=K1rLw1lGMZaw6VPlI0c2e+hxCM9FeMejujw6wy4PgsQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Af4DUZAQQJD/H6KDcjSoOXfM8IYABuJKpeIvQVC30XvH4ZO+GPPbnfsfEkFgbW100 qBOeY4Erya6pukLLBg2vYJKO1zkv3Petm2aEcMTtx2trDv/SkzQ2TPWnLgI3r0AWuK /rkwbk8nM0iNnmr/MigY4VyFLlIJH3tWDnak2A6MAZ5yUUDajc19GK4UC9xQ7tEBk/ 6iGD9WcueyPubcB9a5m0+DP31czCyXoAnyjdceXHlW9GiDV0wbwm5q05F8+14HWWvd 78CHobWIIMwCrcG0rbTMoawCplXB9rnHoRUkBMHZXTO2w3ac6ya+2VSuo/QtBAHyVE 7/VUh9ZvQHS2w== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id D1AAF40AE9; Fri, 1 Aug 2025 00:13:36 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 04/12] docs: kdoc: move the prefix transforms out of dump_struct() Date: Thu, 31 Jul 2025 18:13:18 -0600 Message-ID: <20250801001326.924276-5-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250801001326.924276-1-corbet@lwn.net> References: <20250801001326.924276-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" dump_struct is one of the longest functions in the kdoc_parser class, making it hard to read and reason about. Move the definition of the prefix transformations out of the function, join them with the definition of "attribute" (which was defined at the top of the file but only used here), and reformat the code slightly for shorter line widths. Just code movement in the end. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 178 +++++++++++++++++--------------- 1 file changed, 96 insertions(+), 82 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index e1efa65a3480..5e375318df9c 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -54,8 +54,6 @@ doc_inline_start =3D KernRe(r'^\s*/\*\*\s*$', cache=3DFal= se) doc_inline_sect =3D KernRe(r'\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)', cache=3DF= alse) doc_inline_end =3D KernRe(r'^\s*\*/\s*$', cache=3DFalse) doc_inline_oneline =3D KernRe(r'^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$',= cache=3DFalse) -attribute =3D KernRe(r"__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)", - flags=3Dre.I | re.S, cache=3DFalse) =20 export_symbol =3D KernRe(r'^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*',= cache=3DFalse) export_symbol_ns =3D KernRe(r'^\s*EXPORT_SYMBOL_NS(_GPL)?\s*\(\s*(\w+)\s*,= \s*"\S+"\)\s*', cache=3DFalse) @@ -74,6 +72,97 @@ doc_begin_func =3D KernRe(str(doc_com) + # initial " *= ' r'(?:[-:].*)?$', # description (not captured) cache =3D False) =20 +# +# Here begins a long set of transformations to turn structure member prefi= xes +# and macro invocations into something we can parse and generate kdoc for. +# +struct_attribute =3D KernRe(r"__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)", + flags=3Dre.I | re.S, cache=3DFalse) +struct_args_pattern =3D r'([^,)]+)' + +struct_prefixes =3D [ + # Strip attributes + (struct_attribute, ' '), + (KernRe(r'\s*__aligned\s*\([^;]*\)', re.S), ' '), + (KernRe(r'\s*__counted_by\s*\([^;]*\)', re.S), ' '), + (KernRe(r'\s*__counted_by_(le|be)\s*\([^;]*\)', re.S), ' '), + (KernRe(r'\s*__packed\s*', re.S), ' '), + (KernRe(r'\s*CRYPTO_MINALIGN_ATTR', re.S), ' '), + (KernRe(r'\s*____cacheline_aligned_in_smp', re.S), ' '), + (KernRe(r'\s*____cacheline_aligned', re.S), ' '), + # + # Unwrap struct_group macros based on this definition: + # __struct_group(TAG, NAME, ATTRS, MEMBERS...) + # which has variants like: struct_group(NAME, MEMBERS...) + # Only MEMBERS arguments require documentation. + # + # Parsing them happens on two steps: + # + # 1. drop struct group arguments that aren't at MEMBERS, + # storing them as STRUCT_GROUP(MEMBERS) + # + # 2. remove STRUCT_GROUP() ancillary macro. + # + # The original logic used to remove STRUCT_GROUP() using an + # advanced regex: + # + # \bSTRUCT_GROUP(\(((?:(?>[^)(]+)|(?1))*)\))[^;]*; + # + # with two patterns that are incompatible with + # Python re module, as it has: + # + # - a recursive pattern: (?1) + # - an atomic grouping: (?>...) + # + # I tried a simpler version: but it didn't work either: + # \bSTRUCT_GROUP\(([^\)]+)\)[^;]*; + # + # As it doesn't properly match the end parenthesis on some cases. + # + # So, a better solution was crafted: there's now a NestedMatch + # class that ensures that delimiters after a search are properly + # matched. So, the implementation to drop STRUCT_GROUP() will be + # handled in separate. + # + (KernRe(r'\bstruct_group\s*\(([^,]*,)', re.S), r'STRUCT_GROUP('), + (KernRe(r'\bstruct_group_attr\s*\(([^,]*,){2}', re.S), r'STRUCT_GROUP(= '), + (KernRe(r'\bstruct_group_tagged\s*\(([^,]*),([^,]*),', re.S), r'struct= \1 \2; STRUCT_GROUP('), + (KernRe(r'\b__struct_group\s*\(([^,]*,){3}', re.S), r'STRUCT_GROUP('), + # + # Replace macros + # + # TODO: use NestedMatch for FOO($1, $2, ...) matches + # + # it is better to also move those to the NestedMatch logic, + # to ensure that parenthesis will be properly matched. + # + (KernRe(r'__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^)]+)\)', re.S), + r'DECLARE_BITMAP(\1, __ETHTOOL_LINK_MODE_MASK_NBITS)'), + (KernRe(r'DECLARE_PHY_INTERFACE_MASK\s*\(([^)]+)\)', re.S), + r'DECLARE_BITMAP(\1, PHY_INTERFACE_MODE_MAX)'), + (KernRe(r'DECLARE_BITMAP\s*\(' + struct_args_pattern + r',\s*' + struc= t_args_pattern + r'\)', + re.S), r'unsigned long \1[BITS_TO_LONGS(\2)]'), + (KernRe(r'DECLARE_HASHTABLE\s*\(' + struct_args_pattern + r',\s*' + st= ruct_args_pattern + r'\)', + re.S), r'unsigned long \1[1 << ((\2) - 1)]'), + (KernRe(r'DECLARE_KFIFO\s*\(' + struct_args_pattern + r',\s*' + struct= _args_pattern + + r',\s*' + struct_args_pattern + r'\)', re.S), r'\2 *\1'), + (KernRe(r'DECLARE_KFIFO_PTR\s*\(' + struct_args_pattern + r',\s*' + + struct_args_pattern + r'\)', re.S), r'\2 *\1'), + (KernRe(r'(?:__)?DECLARE_FLEX_ARRAY\s*\(' + struct_args_pattern + r',\= s*' + + struct_args_pattern + r'\)', re.S), r'\1 \2[]'), + (KernRe(r'DEFINE_DMA_UNMAP_ADDR\s*\(' + struct_args_pattern + r'\)', r= e.S), r'dma_addr_t \1'), + (KernRe(r'DEFINE_DMA_UNMAP_LEN\s*\(' + struct_args_pattern + r'\)', re= .S), r'__u32 \1'), +] +# +# Regexes here are guaranteed to have the end limiter matching +# the start delimiter. Yet, right now, only one replace group +# is allowed. +# +struct_nested_prefixes =3D [ + (re.compile(r'\bSTRUCT_GROUP\('), r'\1'), +] + + # # A little helper to get rid of excess white space # @@ -579,90 +668,15 @@ class KernelDoc: f"expecting prototype for {decl_type} {self.entr= y.identifier}. Prototype was for {decl_type} {declaration_name} instead\n") return =20 - args_pattern =3D r'([^,)]+)' - - sub_prefixes =3D [ - # Strip attributes - (attribute, ' '), - (KernRe(r'\s*__aligned\s*\([^;]*\)', re.S), ' '), - (KernRe(r'\s*__counted_by\s*\([^;]*\)', re.S), ' '), - (KernRe(r'\s*__counted_by_(le|be)\s*\([^;]*\)', re.S), ' '), - (KernRe(r'\s*__packed\s*', re.S), ' '), - (KernRe(r'\s*CRYPTO_MINALIGN_ATTR', re.S), ' '), - (KernRe(r'\s*____cacheline_aligned_in_smp', re.S), ' '), - (KernRe(r'\s*____cacheline_aligned', re.S), ' '), - - # Unwrap struct_group macros based on this definition: - # __struct_group(TAG, NAME, ATTRS, MEMBERS...) - # which has variants like: struct_group(NAME, MEMBERS...) - # Only MEMBERS arguments require documentation. - # - # Parsing them happens on two steps: - # - # 1. drop struct group arguments that aren't at MEMBERS, - # storing them as STRUCT_GROUP(MEMBERS) - # - # 2. remove STRUCT_GROUP() ancillary macro. - # - # The original logic used to remove STRUCT_GROUP() using an - # advanced regex: - # - # \bSTRUCT_GROUP(\(((?:(?>[^)(]+)|(?1))*)\))[^;]*; - # - # with two patterns that are incompatible with - # Python re module, as it has: - # - # - a recursive pattern: (?1) - # - an atomic grouping: (?>...) - # - # I tried a simpler version: but it didn't work either: - # \bSTRUCT_GROUP\(([^\)]+)\)[^;]*; - # - # As it doesn't properly match the end parenthesis on some cas= es. - # - # So, a better solution was crafted: there's now a NestedMatch - # class that ensures that delimiters after a search are proper= ly - # matched. So, the implementation to drop STRUCT_GROUP() will = be - # handled in separate. - - (KernRe(r'\bstruct_group\s*\(([^,]*,)', re.S), r'STRUCT_GROUP(= '), - (KernRe(r'\bstruct_group_attr\s*\(([^,]*,){2}', re.S), r'STRUC= T_GROUP('), - (KernRe(r'\bstruct_group_tagged\s*\(([^,]*),([^,]*),', re.S), = r'struct \1 \2; STRUCT_GROUP('), - (KernRe(r'\b__struct_group\s*\(([^,]*,){3}', re.S), r'STRUCT_G= ROUP('), - - # Replace macros - # - # TODO: use NestedMatch for FOO($1, $2, ...) matches - # - # it is better to also move those to the NestedMatch logic, - # to ensure that parenthesis will be properly matched. - - (KernRe(r'__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^)]+)\)', re.= S), r'DECLARE_BITMAP(\1, __ETHTOOL_LINK_MODE_MASK_NBITS)'), - (KernRe(r'DECLARE_PHY_INTERFACE_MASK\s*\(([^)]+)\)', re.S), r'= DECLARE_BITMAP(\1, PHY_INTERFACE_MODE_MAX)'), - (KernRe(r'DECLARE_BITMAP\s*\(' + args_pattern + r',\s*' + args= _pattern + r'\)', re.S), r'unsigned long \1[BITS_TO_LONGS(\2)]'), - (KernRe(r'DECLARE_HASHTABLE\s*\(' + args_pattern + r',\s*' + a= rgs_pattern + r'\)', re.S), r'unsigned long \1[1 << ((\2) - 1)]'), - (KernRe(r'DECLARE_KFIFO\s*\(' + args_pattern + r',\s*' + args_= pattern + r',\s*' + args_pattern + r'\)', re.S), r'\2 *\1'), - (KernRe(r'DECLARE_KFIFO_PTR\s*\(' + args_pattern + r',\s*' + a= rgs_pattern + r'\)', re.S), r'\2 *\1'), - (KernRe(r'(?:__)?DECLARE_FLEX_ARRAY\s*\(' + args_pattern + r',= \s*' + args_pattern + r'\)', re.S), r'\1 \2[]'), - (KernRe(r'DEFINE_DMA_UNMAP_ADDR\s*\(' + args_pattern + r'\)', = re.S), r'dma_addr_t \1'), - (KernRe(r'DEFINE_DMA_UNMAP_LEN\s*\(' + args_pattern + r'\)', r= e.S), r'__u32 \1'), - ] - - # Regexes here are guaranteed to have the end limiter matching - # the start delimiter. Yet, right now, only one replace group - # is allowed. - - sub_nested_prefixes =3D [ - (re.compile(r'\bSTRUCT_GROUP\('), r'\1'), - ] - + # + # Go through the list of members applying all of our transformatio= ns. + # members =3D trim_private_members(members) - for search, sub in sub_prefixes: + for search, sub in struct_prefixes: members =3D search.sub(sub, members) =20 nested =3D NestedMatch() - - for search, sub in sub_nested_prefixes: + for search, sub in struct_nested_prefixes: members =3D nested.sub(search, sub, members) =20 # Keeps the original declaration as-is --=20 2.50.1 From nobody Sun Oct 5 16:20:38 2025 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 79EF18F49; Fri, 1 Aug 2025 00:13:43 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754007225; cv=none; b=CDeU4BP8jesYJDfNVr7dxhipKc/VJ1Kzx5AKGohOdrCpjaNFiiy2FX0jMS0GdUuiCYy4qAA0kMLvMKBGhJ/NvYVdlUxyd9SenpheR3YmPfDZMMsAvFReY8cPAchN5w/ABnSRam074/W6/sHiYlLlsOYROarFdByz8qPW2QC8zWI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754007225; c=relaxed/simple; bh=zMNGkKDVtrQYR1g6zgUl8wLnLKe4Yun+oWNyM5XI148=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=W5v6/mhqjUI9V13g1VXffCa17dBKF7NtoTHkNk67+sCXotzNqXN/O/7vtafeckhu0oRcQ8sBdmNsczxmv76vHdqikjsHlsrHh/VxBQ7khsk1dFLmNdHiOYSs73UUmLn1czRr8qQQKjtjtwDFk7m5jzVmfULSTMx9LY5ik16U25A= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=Ep9y+nvM; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="Ep9y+nvM" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 635CD40AEA DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1754007217; bh=Mq7zonfROPmRJEB1Vu+YlKjYMNVLogYxufUGthhqAMI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Ep9y+nvMg4DP2tYtX47Zdh//cOTkLUXRGZjNabtX+LXM4divpOWoucShqG0ssjYyB VVtMx6ydPIJG9ruvjPRjfLPZaT/0hvnSvlNyGNU3hd51QTklrVpbxhfECszz1/oQ1s GxYbwDxrqa0YRXg3HEg0BfP6EX6MqeJRh0h15H2X+xbg3JutfWwjKYAyD9VSWeWFJb FAWCs6tOOKv6fKWoK9cEqfiP8mY6tz/aGiBhZMhAgJiVLtScZ5loD4k77yXZPAljXk KCNMdyE7wiOdpTAvSdV6l9QPSRxxfv0d0ID2V5uPKMkOTakdYjpQUvwQo2OR7m+z6t vOFbeLgv/X2PQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 635CD40AEA; Fri, 1 Aug 2025 00:13:37 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 05/12] docs: kdoc: split top-level prototype parsing out of dump_struct() Date: Thu, 31 Jul 2025 18:13:19 -0600 Message-ID: <20250801001326.924276-6-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250801001326.924276-1-corbet@lwn.net> References: <20250801001326.924276-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Move the initial split of the prototype into its own function in the ongoing effort to cut dump_struct() down to size. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 44 +++++++++++++++------------------ 1 file changed, 20 insertions(+), 24 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 5e375318df9c..2bb0da22048f 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -624,13 +624,11 @@ class KernelDoc: self.emit_msg(ln, f"No description found for return value of '{dec= laration_name}'") =20 - def dump_struct(self, ln, proto): - """ - Store an entry for an struct or union - """ - + # + # Split apart a structure prototype; returns (struct|union, name, memb= ers) or None + # + def split_struct_proto(self, proto): type_pattern =3D r'(struct|union)' - qualifiers =3D [ "__attribute__", "__packed", @@ -638,36 +636,34 @@ class KernelDoc: "____cacheline_aligned_in_smp", "____cacheline_aligned", ] - definition_body =3D r'\{(.*)\}\s*' + "(?:" + '|'.join(qualifiers) = + ")?" =20 - # Extract struct/union definition - members =3D None - declaration_name =3D None - decl_type =3D None - r =3D KernRe(type_pattern + r'\s+(\w+)\s*' + definition_body) if r.search(proto): - decl_type =3D r.group(1) - declaration_name =3D r.group(2) - members =3D r.group(3) + return (r.group(1), r.group(2), r.group(3)) else: r =3D KernRe(r'typedef\s+' + type_pattern + r'\s*' + definitio= n_body + r'\s*(\w+)\s*;') - if r.search(proto): - decl_type =3D r.group(1) - declaration_name =3D r.group(3) - members =3D r.group(2) + return (r.group(1), r.group(3), r.group(2)) + return None =20 - if not members: + def dump_struct(self, ln, proto): + """ + Store an entry for an struct or union + """ + # + # Do the basic parse to get the pieces of the declaration. + # + struct_parts =3D self.split_struct_proto(proto) + if not struct_parts: self.emit_msg(ln, f"{proto} error: Cannot parse struct or unio= n!") return + decl_type, declaration_name, members =3D struct_parts =20 if self.entry.identifier !=3D declaration_name: - self.emit_msg(ln, - f"expecting prototype for {decl_type} {self.entr= y.identifier}. Prototype was for {decl_type} {declaration_name} instead\n") + self.emit_msg(ln, f"expecting prototype for {decl_type} {self.= entry.identifier}. " + f"Prototype was for {decl_type} {declaration_nam= e} instead\n") return - # # Go through the list of members applying all of our transformatio= ns. # @@ -696,7 +692,7 @@ class KernelDoc: # So, we need to have an extra loop on Python to override such # re limitation. =20 - struct_members =3D KernRe(type_pattern + r'([^{};]+)(\{)([^{}]*)(\= })([^{};]*)(;)') + struct_members =3D KernRe(r'(struct|union)([^{};]+)(\{)([^{}]*)(\}= )([^{};]*)(;)') while True: tuples =3D struct_members.findall(members) if not tuples: --=20 2.50.1 From nobody Sun Oct 5 16:20:38 2025 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 79D0979FE; Fri, 1 Aug 2025 00:13:43 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754007226; cv=none; b=YHn1jMK/5369qcUAvfdk9LkIyaJRPfk+Ly2fOicOPQOaBrsKcF5CSMXjlDPKm557oyW3AaDUu7nqpIDcaI/CazsoNaeuvLFDQ0ggq5LCsS2qwZhzJ9mLwBN96gHfs2Iz5DnytQ52resd1dbz5mufSJ81qzMFrPAq53T0FgHGD+U= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754007226; c=relaxed/simple; bh=nSu3sd4zO5fsEW54GGSTyH9Gaz2ZPGqxpG/A+jYGb10=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=AnPRrP2OyLx+pqZaE7RjkvWesSSpxBufS8y8fSpVKMLWtI28poxuq8BM2jUG5ho9wAs0r6tA1uN69NgsKxMi4wxCH4RYmiUtb2qLNPXMSL4dCPMl/TdWP0JJ9NfXk8gXOxHPRnjq46OKE9So0OudUuBAtSigBU4eBSIjcG7ZaFM= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=RvE1tyyv; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="RvE1tyyv" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 00F7F40AEB DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1754007218; bh=GZtVIHs+qGS2JnvOEqLwKgsnB7hdteAAz8AZ24kN6ss=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=RvE1tyyv6fx+NbE5qmJStYIVmysXNqVwNphIV9teMslYegDY3atbh/TKX+n7PTwpL VXOMQPF7LI50qzGcDV+ENfvbB7yJzA5+0RXWhygX9QewdapCKoBFmPRqZ72zo0rfbu hxUd4bv63fj0M4z1MiTooLY3QeFpDM9kf8juICoAxWy2F1YfIwOFzZexyIjwMHAcWH Yg1BITWSp+QVitbVPE3JzANtDoyREx7GURuicHZQzylA5XAKJrnLT1erGoQMk5nw0G 0cP/MBOCOs7uT0vg7oR64MRK85hXN7ywo/oxE5WcnERXve4wByzq4K0Il9StW8gyfQ nP9XNmp5kWuFQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 00F7F40AEB; Fri, 1 Aug 2025 00:13:37 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 06/12] docs: kdoc: split struct-member rewriting out of dump_struct() Date: Thu, 31 Jul 2025 18:13:20 -0600 Message-ID: <20250801001326.924276-7-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250801001326.924276-1-corbet@lwn.net> References: <20250801001326.924276-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" The massive loop that massages struct members shares no data with the rest of dump_struct(); split it out into its own function. Code movement only, no other changes. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 65 +++++++++++++++++---------------- 1 file changed, 34 insertions(+), 31 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 2bb0da22048f..5c4ad8febb9f 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -647,37 +647,7 @@ class KernelDoc: return (r.group(1), r.group(3), r.group(2)) return None =20 - def dump_struct(self, ln, proto): - """ - Store an entry for an struct or union - """ - # - # Do the basic parse to get the pieces of the declaration. - # - struct_parts =3D self.split_struct_proto(proto) - if not struct_parts: - self.emit_msg(ln, f"{proto} error: Cannot parse struct or unio= n!") - return - decl_type, declaration_name, members =3D struct_parts - - if self.entry.identifier !=3D declaration_name: - self.emit_msg(ln, f"expecting prototype for {decl_type} {self.= entry.identifier}. " - f"Prototype was for {decl_type} {declaration_nam= e} instead\n") - return - # - # Go through the list of members applying all of our transformatio= ns. - # - members =3D trim_private_members(members) - for search, sub in struct_prefixes: - members =3D search.sub(sub, members) - - nested =3D NestedMatch() - for search, sub in struct_nested_prefixes: - members =3D nested.sub(search, sub, members) - - # Keeps the original declaration as-is - declaration =3D members - + def rewrite_struct_members(self, members): # Split nested struct/union elements # # This loop was simpler at the original kernel-doc perl version, as @@ -768,6 +738,39 @@ class KernelDoc: newmember +=3D f"{dtype} {s_id}.{name}= ; " =20 members =3D members.replace(oldmember, newmember) + return members + + def dump_struct(self, ln, proto): + """ + Store an entry for an struct or union + """ + # + # Do the basic parse to get the pieces of the declaration. + # + struct_parts =3D self.split_struct_proto(proto) + if not struct_parts: + self.emit_msg(ln, f"{proto} error: Cannot parse struct or unio= n!") + return + decl_type, declaration_name, members =3D struct_parts + + if self.entry.identifier !=3D declaration_name: + self.emit_msg(ln, f"expecting prototype for {decl_type} {self.= entry.identifier}. " + f"Prototype was for {decl_type} {declaration_nam= e} instead\n") + return + # + # Go through the list of members applying all of our transformatio= ns. + # + members =3D trim_private_members(members) + for search, sub in struct_prefixes: + members =3D search.sub(sub, members) + + nested =3D NestedMatch() + for search, sub in struct_nested_prefixes: + members =3D nested.sub(search, sub, members) + + # Keeps the original declaration as-is + declaration =3D members + members =3D self.rewrite_struct_members(members) =20 # Ignore other nested elements, like enums members =3D re.sub(r'(\{[^\{\}]*\})', '', members) --=20 2.50.1 From nobody Sun Oct 5 16:20:38 2025 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 79CD06ADD; Fri, 1 Aug 2025 00:13:43 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754007225; cv=none; b=ebnFKjndCLDsXutwGuKsqCoytrvjpVKJPzHaKaVpW3v7M65C62jgmH6doTetQohe8QZXYD4Jy32mMvwUuHeHJbKDxzxyHwTU2T57HnoG9fy8mHiOI9qTx7GcMJkIOj68UTw2MzPDusgP/XEPq+XDYjP0c3DMFoc797SCwjfWbrI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754007225; c=relaxed/simple; bh=AobM2Kpc01QvA+kOgc8gyZRMbf6boLHS4knPy8pT+ek=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=DQ8vkkWQ+qZwXqLo1ceGO0nT2pZArkEe0SrkoTP3uDUyjWnjWNBqg44fy39KygNOjVDP8dP5yPRmqQFZquO9pPODzKOUiPAUswRQkqgK73DVzSwEFT7PnjWx1LHA8kpRPq4aig8s9nLwqS4UQNsIZULguMGLcq96kHPMGUYU/q8= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=Aj0oz6j4; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="Aj0oz6j4" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 8EFA440AED DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1754007219; bh=7nfDzqe9mxKKh3BHeIroRqaSenA+9Y00nOCwi9jfqt4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Aj0oz6j4ej+8DbPm9xtjXKqoJ4QHVsFQCpSSydK+5pC06i5pQskNRJWMPZDlugS0O GVZlli0lEn7mDzwrTgZxVKfP+rl4m/7O+UGth4ztaG41U3xTlb4+3qalsOYgVmo7+k bw3k/NsR/EVXzDxEicWmEaWq4kMUM3TNwySppbf8zmXYNAaXHSDF4UNAV76k1T8OFY q0yUFq2SfKFMjSRbNYkWEg6xNa8QXSqimhHD/V0RgmkhJTd5lEILIlU3RhrnjpmejC MayPxi2EAb5H2XxusibvarfRPV1Pen2V/mnBehkl1MTY0JoQKEiifyHFkHgN0h+9Qu su701h+uzjI0w== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 8EFA440AED; Fri, 1 Aug 2025 00:13:38 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 07/12] docs: kdoc: rework the rewrite_struct_members() main loop Date: Thu, 31 Jul 2025 18:13:21 -0600 Message-ID: <20250801001326.924276-8-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250801001326.924276-1-corbet@lwn.net> References: <20250801001326.924276-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Adopt a more Pythonic form for the main loop of this function, getting rid of the "while True:" construction and making the actual loop invariant explicit. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 5c4ad8febb9f..efc5888fcc74 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -663,11 +663,8 @@ class KernelDoc: # re limitation. =20 struct_members =3D KernRe(r'(struct|union)([^{};]+)(\{)([^{}]*)(\}= )([^{};]*)(;)') - while True: - tuples =3D struct_members.findall(members) - if not tuples: - break - + tuples =3D struct_members.findall(members) + while tuples: for t in tuples: newmember =3D "" maintype =3D t[0] @@ -738,6 +735,7 @@ class KernelDoc: newmember +=3D f"{dtype} {s_id}.{name}= ; " =20 members =3D members.replace(oldmember, newmember) + tuples =3D struct_members.findall(members) return members =20 def dump_struct(self, ln, proto): --=20 2.50.1 From nobody Sun Oct 5 16:20:38 2025 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 79D438C11; Fri, 1 Aug 2025 00:13:43 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754007225; cv=none; b=fyQ/nXWXktLGMEkN7oJJnQoQA80HAgaSVqLe/X2xkwu+0DgcEHDq667NLPML0hFO2ufKELw07XMatCzT9KxO6z8GjKZSYWJp/Yn5BrKMM2xii51Gf5pl1DSJZXccitvhXGfiuJVq/SZZtYpFKqNKFIxJ//i3+9v5Ehi5DCiDcKY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754007225; c=relaxed/simple; bh=op22pxxfC1qXD09BhvHCY4wVeYqrF211zaxQRQ5DQNY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=hquIw6nycrGkwuqsO+BDNvZRjk+aq4iEKe7De9eiqAp+HX1cUPaWhxLbOvoX8aFoGiYksEOhYRhVRXydfgW0zxHOwdOKbZ4/HNqmA1gJ1ydkcKVYZFliVRAQNbEr7rIKdy20SXVzsKuUIBfNBS0b8NXZqwQNYYHVrnGhr4KR7KE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=Nb7Cykvc; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="Nb7Cykvc" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 4AD7040AEE DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1754007219; bh=R152Lx6LEIOU/wqrwvCtDXqUSZvnz4jIXtOr3wAg6rI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Nb7CykvcmOdg/uTT4ramExxz3hH4zXGTjOgr+InFxSAeII8IKneVKRLpWwRzzEaQj r2XtCAqSWR9krju+8th6MoR8vhA84ZWHZARo1dXY08acBhjKofSRCOZHWWUnSyZ1IO HA0dqfhKX72WB1C0W2T7B3iSX1z4khQg12bXFjG5FuLUcwV+ffy3qOlXv2a4oJp49e 1uLgQUHhSWrb5ygiSgsIB4m0ybiQ1TIC3V7Vao8eWxS/9vm74lmjbY06Gpjja7pXQM VZBr0Oqbfc/Q4sKFuXYAvZ5W4qxgDgxgpu0wtA0DErpifARgeP1hiLoXOUooOHEhcz EJK6WQbE11uCA== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 4AD7040AEE; Fri, 1 Aug 2025 00:13:39 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 08/12] docs: kdoc: remove an extraneous strip() call Date: Thu, 31 Jul 2025 18:13:22 -0600 Message-ID: <20250801001326.924276-9-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250801001326.924276-1-corbet@lwn.net> References: <20250801001326.924276-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" ...the variable in question was already strip()ed at the top of the loop. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 1 - 1 file changed, 1 deletion(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index efc5888fcc74..b751fa8edde7 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -703,7 +703,6 @@ class KernelDoc: newmember +=3D f"{dtype}{s_id}.{name}{extr= a}; " =20 else: - arg =3D arg.strip() # Handle bitmaps arg =3D KernRe(r':\s*\d+\s*').sub('', arg) =20 --=20 2.50.1 From nobody Sun Oct 5 16:20:38 2025 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id AB2DE179A3; Fri, 1 Aug 2025 00:13:44 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754007226; cv=none; b=Yq/pWrJu7odXTSzXVzhT6J83v9kVQhbDl7EqjrBXsyPDymsVEUq1jFrbCEHJmpCbCGL8FskKLqbmBZ7tQFoEWY+bycturPY0J4zbcBdMYauEgnXoJxmhOIKCAdrbbgxGaFZ+bkdslbbS53V6rZlsN6L5DLgcVyE1sBJMvjLTtPk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754007226; c=relaxed/simple; bh=UikgWuPl67D/fNXakHTxUd2A5vqqMgc5WiNC02gmeGg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=kbLgqhFikDBpg382TSzdXov6aHT+yMogsS0YaXlnKc+q+9k6DryMINhvNCUlZJzHXmPxN6nGyZGlGAnCoL8TvEOcGV4iT57cCaAHZMvxWXFwJswDtqvWEFGUkTv4qqehhbCEvb5VlFqbbeGOgSvpy2QkqavNxQfMD9Dw5W46dMc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=BlIlbcrt; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="BlIlbcrt" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net D958D40AF0 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1754007220; bh=XNEzhTSVAQRzQDjIcMHPoA90wuZD9B/p03R0VwgAYLI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=BlIlbcrtL3BfQu0xw9JhefSpRJtlD0HAVmNyf+YLe4iWiSrd/wGngYxBsy5tW1vq5 BKTO/sOdIm+22avgUcg5xiXh7OQNbE/3cyVTAnq1R8xuAoFc7+m9r6nPFdLGLvaj3s cymdd8uZWnzzO04pajw62DVxUzv8MQodP/bhX37hI/YISJR3RSWZfW3pQuwM/Q4RF3 K6VOM3d6V6Csn7xAzglB7cc5KE5BPuUQpBRcyLxbtWDQTH/tZWu0NzrnDkZx9mfdC4 wY/sHUqwXjzx7ij+1yL5w7O4q5O2kn2MSRtU8V+Co63QijxYaBZAeNtJVSzw4hLl1v u2edIC/K/owuw== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id D958D40AF0; Fri, 1 Aug 2025 00:13:39 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 09/12] docs: kdoc: Some rewrite_struct_members() commenting Date: Thu, 31 Jul 2025 18:13:23 -0600 Message-ID: <20250801001326.924276-10-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250801001326.924276-1-corbet@lwn.net> References: <20250801001326.924276-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Add comments to rewrite_struct_members() describing what it is actually doing, and reformat/comment the main struct_members regex so that it is (more) comprehensible to humans. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 32 +++++++++++++++++++------------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index b751fa8edde7..20e0a2abe13b 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -647,22 +647,28 @@ class KernelDoc: return (r.group(1), r.group(3), r.group(2)) return None =20 + # + # Rewrite the members of a structure or union for easier formatting la= ter on. + # Among other things, this function will turn a member like: + # + # struct { inner_members; } foo; + # + # into: + # + # struct foo; inner_members; + # def rewrite_struct_members(self, members): - # Split nested struct/union elements - # - # This loop was simpler at the original kernel-doc perl version, as - # while ($members =3D~ m/$struct_members/) { ... } - # reads 'members' string on each interaction. # - # Python behavior is different: it parses 'members' only once, - # creating a list of tuples from the first interaction. + # Process struct/union members from the most deeply nested outward= . The + # trick is in the ^{ below - it prevents a match of an outer struc= t/union + # until the inner one has been munged (removing the "{" in the pro= cess). # - # On other words, this won't get nested structs. - # - # So, we need to have an extra loop on Python to override such - # re limitation. - - struct_members =3D KernRe(r'(struct|union)([^{};]+)(\{)([^{}]*)(\}= )([^{};]*)(;)') + struct_members =3D KernRe(r'(struct|union)' # 0: declaration type + r'([^{};]+)' # 1: possible name + r'(\{)' + r'([^{}]*)' # 3: Contents of declara= tion + r'(\})' + r'([^{};]*)(;)') # 5: Remaining stuff aft= er declaration tuples =3D struct_members.findall(members) while tuples: for t in tuples: --=20 2.50.1 From nobody Sun Oct 5 16:20:38 2025 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id D2B021B95B; Fri, 1 Aug 2025 00:13:44 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754007227; cv=none; b=CPmA9QNni5PGNH+iMqmykV4WpYFPVebbrIDrOaGUGqgrJZMgbYg+Y3e+8QFBs1On+36FFLxNUehKOoJCs14LNJZ13lJ/ggd3u5iR79Udtyw4buCvYltL/XlYbu4Cnba6u4DMmIMmnisvyqA+L4vHHyO4QoXJHvJ2ca4jG4MzNAw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754007227; c=relaxed/simple; bh=H6p72Ss8kbUZeWCCe4TABpW5lDHCvzbrOV6nIqxbz9g=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=J9mgSTKP0ch4/xDuoHpTa8ZmHVHE8pd6B5tmOhz6oHkjduR1oYWfVQbTlI7WIocAnHyi83iLJIZD9rtchuQGRRdEp9YqV3i4LNPiV5ZGLAbZa5jRimWzLBoCL0wa7mBKtchdUyz4dcGC/UcSrt/9ZQwIp7iy/8NmSmAycjKhp+8= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=SOIZKUDw; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="SOIZKUDw" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 6633940AF1 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1754007220; bh=hNNZNp01RtrW+DLUWFXNUyvzDohZ34N8ED3quRO1A40=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=SOIZKUDwJkRlXyZOvCmn6ppvAoTPQoRA4h4LPJxpM356DthOa5E+Jira8r46rM4tC iXam7jf6CLbzleWSPVvK0bJC2VjV6uHKJ+GV5XoTeC38dtGKY3o6oQoDA9ymjHbQ3x aJkaXjFS6Uz+bznh8rfdoIMV8cOnhe0w7F9L+gvrwJUnLtXxAN9da/Z6xkyHL6eX1q iifemJXnlAHCLWc6HolvLZ1G8kTb2/f+z/+ddic6sZGTupLeDaz1E2eHuUP+CtLEut RXG/C1zR/QuSk25McXZ81Wym1n+LVwLm1LGYV0JsxhgHuVbC3JpLIt759YGbOGaEcg 5x/twsIQYMjsA== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 6633940AF1; Fri, 1 Aug 2025 00:13:40 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 10/12] docs: kdoc: further rewrite_struct_members() cleanup Date: Thu, 31 Jul 2025 18:13:24 -0600 Message-ID: <20250801001326.924276-11-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250801001326.924276-1-corbet@lwn.net> References: <20250801001326.924276-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Get rid of some single-use variables and redundant checks, and generally tighten up the code; no logical change. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 89 ++++++++++++++++----------------- 1 file changed, 42 insertions(+), 47 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 20e0a2abe13b..2b7d7e646367 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -673,73 +673,68 @@ class KernelDoc: while tuples: for t in tuples: newmember =3D "" - maintype =3D t[0] - s_ids =3D t[5] - content =3D t[3] - - oldmember =3D "".join(t) - - for s_id in s_ids.split(','): + oldmember =3D "".join(t) # Reconstruct the original format= ting + # + # Pass through each field name, normalizing the form and f= ormatting. + # + for s_id in t[5].split(','): s_id =3D s_id.strip() =20 - newmember +=3D f"{maintype} {s_id}; " + newmember +=3D f"{t[0]} {s_id}; " + # + # Remove bitfield/array/pointer info, getting the bare= name. + # s_id =3D KernRe(r'[:[].*').sub('', s_id) s_id =3D KernRe(r'^\s*\**(\S+)\s*').sub(r'\1', s_id) - - for arg in content.split(';'): + # + # Pass through the members of this inner structure/uni= on. + # + for arg in t[3].split(';'): arg =3D arg.strip() - - if not arg: - continue - + # + # Look for (type)(*name)(args) - pointer to functi= on + # r =3D KernRe(r'^([^(]+\(\*?\s*)([\w.]*)(\s*\).*)') if r.match(arg): # Pointer-to-function - dtype =3D r.group(1) - name =3D r.group(2) - extra =3D r.group(3) - - if not name: - continue - if not s_id: # Anonymous struct/union - newmember +=3D f"{dtype}{name}{extra}; " + newmember +=3D f"{r.group(1)}{r.group(2)}{= r.group(3)}; " else: - newmember +=3D f"{dtype}{s_id}.{name}{extr= a}; " - + newmember +=3D f"{r.group(1)}{s_id}.{r.gro= up(2)}{r.group(3)}; " + # + # Otherwise a non-function member. + # else: - # Handle bitmaps + # + # Remove bitmap and array portions and spaces = around commas + # arg =3D KernRe(r':\s*\d+\s*').sub('', arg) - - # Handle arrays arg =3D KernRe(r'\[.*\]').sub('', arg) - - # Handle multiple IDs arg =3D KernRe(r'\s*,\s*').sub(',', arg) - + # + # Look for a normal decl - "type name[,name...= ]" + # r =3D KernRe(r'(.*)\s+([\S+,]+)') - if r.search(arg): - dtype =3D r.group(1) - names =3D r.group(2) + for name in r.group(2).split(','): + name =3D KernRe(r'^\s*\**(\S+)\s*').su= b(r'\1', name) + if not s_id: + # Anonymous struct/union + newmember +=3D f"{r.group(1)} {nam= e}; " + else: + newmember +=3D f"{r.group(1)} {s_i= d}.{name}; " else: newmember +=3D f"{arg}; " - continue - - for name in names.split(','): - name =3D KernRe(r'^\s*\**(\S+)\s*').sub(r'= \1', name).strip() - - if not name: - continue - - if not s_id: - # Anonymous struct/union - newmember +=3D f"{dtype} {name}; " - else: - newmember +=3D f"{dtype} {s_id}.{name}= ; " - + # + # At the end of the s_id loop, replace the original declar= ation with + # the munged version. + # members =3D members.replace(oldmember, newmember) + # + # End of the tuple loop - search again and see if there are ou= ter members + # that now turn up. + # tuples =3D struct_members.findall(members) return members =20 --=20 2.50.1 From nobody Sun Oct 5 16:20:38 2025 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id D0C8633DF; Fri, 1 Aug 2025 00:13:44 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754007227; cv=none; b=Bp6Cb1JM8JXc3S/C/LLVJyXuk6+sIHxXYk9idxfzZuid8gSF8ac1rcGR1pWv+3nhgEUNReymuyefOHSkc8YWIqhfMMj2w0NVirUvaKKgTEuZoSA1fpK5xDvEsv6+YPsum1z8MuonyeQDB5XXO2iaMEwGMjXT20dytUHiwvG2m6Y= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754007227; c=relaxed/simple; bh=cySWM4d6Zu1D+4PkGvnJjrzGxriO8AGGSEx5r9Yti8g=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=dBhYtGV4OEB7R3AzNcppfwpdgK9QsJ+wAqjgSSFfdqUgmnUIArXmGzM1eZt4G13MBB6svsHCD/HPhLEC0Zaf7pWUpYiDTKlShgy+7hjoauvUrHj1AfmZTLp+6BHYDuwKZn4c7mW2Xv7BKnAI7Vz/v7UqUdT6NOJmZQLC2x1zvcI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=pGlv1bbO; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="pGlv1bbO" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net E819940AF2 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1754007221; bh=Gq5Dfzv5xqo7YhSMK7c2zzkvwfQxptpVHiU1PPp2vYw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=pGlv1bbOQnqLgpLptUlxRNnWkyLDkweZI2RuoAvyXxdH07hquY+I3pOixfV5qqcNc /jrhiwr4u5qkDWPGH/dgd322l661UmBujsC5RriaNj6Jp7384mfiamlADkJ98/ZO2u FuNm45Vb5zNChBHX7cStXO5OFE3MXBqywRyRjp8fQq2yQAGDaoN6e3h9c3eDSoINVH 1SUYJay9yJyrg5HO2lHkwFaplS2ZgSHxRPc+GDF8U7cW38PpqE9MuSa9tTINUohsmX T6CExqNLKraM72yWd3Q6K9rYjH0fTMI0Y9AseuhJJDc/U5xlZugUjTvBlPgI925qHa xkqhiU0/89s+w== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id E819940AF2; Fri, 1 Aug 2025 00:13:40 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 11/12] docs: kdoc: extract output formatting from dump_struct() Date: Thu, 31 Jul 2025 18:13:25 -0600 Message-ID: <20250801001326.924276-12-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250801001326.924276-1-corbet@lwn.net> References: <20250801001326.924276-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" The last thing done in dump_struct() is to format the structure for printing. That, too, is a separate activity; split it out into its own function. dump_struct() now fits in a single, full-hight editor screen. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 72 +++++++++++++++++---------------- 1 file changed, 37 insertions(+), 35 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 2b7d7e646367..131956d89f84 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -738,6 +738,42 @@ class KernelDoc: tuples =3D struct_members.findall(members) return members =20 + # + # Format the struct declaration into a standard form for inclusion in = the + # resulting docs. + # + def format_struct_decl(self, declaration): + # + # Insert newlines, get rid of extra spaces. + # + declaration =3D KernRe(r'([{;])').sub(r'\1\n', declaration) + declaration =3D KernRe(r'\}\s+;').sub('};', declaration) + # + # Format inline enums with each member on its own line. + # + r =3D KernRe(r'(enum\s+\{[^}]+),([^\n])') + while r.search(declaration): + declaration =3D r.sub(r'\1,\n\2', declaration) + # + # Now go through and supply the right number of tabs + # for each line. + # + def_args =3D declaration.split('\n') + level =3D 1 + declaration =3D "" + for clause in def_args: + clause =3D KernRe(r'\s+').sub(' ', clause.strip(), count=3D1) + if clause: + if '}' in clause and level > 1: + level -=3D 1 + if not clause.startswith('#'): + declaration +=3D "\t" * level + declaration +=3D "\t" + clause + "\n" + if "{" in clause and "}" not in clause: + level +=3D 1 + return declaration + + def dump_struct(self, ln, proto): """ Store an entry for an struct or union @@ -776,42 +812,8 @@ class KernelDoc: self.create_parameter_list(ln, decl_type, members, ';', declaration_name) self.check_sections(ln, declaration_name, decl_type) - - # Adjust declaration for better display - declaration =3D KernRe(r'([{;])').sub(r'\1\n', declaration) - declaration =3D KernRe(r'\}\s+;').sub('};', declaration) - - # Better handle inlined enums - while True: - r =3D KernRe(r'(enum\s+\{[^}]+),([^\n])') - if not r.search(declaration): - break - - declaration =3D r.sub(r'\1,\n\2', declaration) - - def_args =3D declaration.split('\n') - level =3D 1 - declaration =3D "" - for clause in def_args: - - clause =3D clause.strip() - clause =3D KernRe(r'\s+').sub(' ', clause, count=3D1) - - if not clause: - continue - - if '}' in clause and level > 1: - level -=3D 1 - - if not KernRe(r'^\s*#').match(clause): - declaration +=3D "\t" * level - - declaration +=3D "\t" + clause + "\n" - if "{" in clause and "}" not in clause: - level +=3D 1 - self.output_declaration(decl_type, declaration_name, - definition=3Ddeclaration, + definition=3Dself.format_struct_decl(decla= ration), purpose=3Dself.entry.declaration_purpose) =20 def dump_enum(self, ln, proto): --=20 2.50.1 From nobody Sun Oct 5 16:20:38 2025 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id D11721B7F4; Fri, 1 Aug 2025 00:13:44 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754007227; cv=none; b=SeU137ENivUzjgfkWTUdfnqO7SmcGjQPtDvOuPDQO5Xdvo9zTWDX2FrkujmlbKTyVJcHkelJqfPF26wc8+bFDqIZcZ8SCF3O1yBHza1X2RmCxskXeFa/MTyN52nIfeGeixVUAoO9jm3AcCq+dWyYLuQ6XYBWMtqJMf4Kt7ONwRA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754007227; c=relaxed/simple; bh=frcYFnmG0494T3FY+1nGa2e/mEUxGzhuM4LmaELetMk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=CBz7xrMTaHXufIKH+6xCd2FeVwQiPh08F8j/yndO4uCZeSazO9Ys663fyLJNDnX7kSqKKUi2lopYiNLEPYJVrx6z+hTpuagteRy30yHP2HxVYgTIcr+m2nIXH5dzxt1Lu33v3ZzikB35oa6bHHg8JAut1DOpqIzSfwikWFFI/0I= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=tYR9sZR6; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="tYR9sZR6" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 77BFF40AF3 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1754007221; bh=7BavdRyyfUuS3E2LBEfR5bO38C3nR3zuf6VYXzSLSuY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=tYR9sZR6Pi7qkJ+QUZB05aTSKAhnhFgwrguRwf4DH86aPEdPrKE8WSagTtEIQ7lRS zIJ0JdBqr+1oYYKon0sV3sL7Z/oh079xy9XHE2DXspd1/RSKZE+doP75Z7fRoaMQwy V0CKl43PFhMI7g/D02lwOVJ/KB38uJdpv1zLpDpA8Er/JboVNsB/w09L/xQgTnx/Hc DhT1Fqk1me+bsAK3cAIrHx9GpA1wIolgwDuZAybXUTboVkcB7jzV8XFwxBOcl5yS2I O+9oKIhqqgBMbtQ1Qg4YeVvWzIiN0XwQRwCF2DTFg4f6EFzfnH7xM77Lsp6lCtPeLJ RtOF+x/eyy2sA== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 77BFF40AF3; Fri, 1 Aug 2025 00:13:41 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Mauro Carvalho Chehab , Akira Yokosawa , Jonathan Corbet Subject: [PATCH 12/12] docs: kdoc: a few final dump_struct() touches Date: Thu, 31 Jul 2025 18:13:26 -0600 Message-ID: <20250801001326.924276-13-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250801001326.924276-1-corbet@lwn.net> References: <20250801001326.924276-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Add a couple more comments so that each phase of the process is now clearly marked. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_parser.py | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 131956d89f84..fa2041276f8c 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -801,14 +801,15 @@ class KernelDoc: nested =3D NestedMatch() for search, sub in struct_nested_prefixes: members =3D nested.sub(search, sub, members) - - # Keeps the original declaration as-is + # + # Deal with embedded struct and union members, and drop enums enti= rely. + # declaration =3D members members =3D self.rewrite_struct_members(members) - - # Ignore other nested elements, like enums members =3D re.sub(r'(\{[^\{\}]*\})', '', members) - + # + # Output the result and we are done. + # self.create_parameter_list(ln, decl_type, members, ';', declaration_name) self.check_sections(ln, declaration_name, decl_type) --=20 2.50.1