From nobody Sun Oct 5 05:29:30 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 7FFB324886C; Thu, 7 Aug 2025 21:16:56 +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=1754601418; cv=none; b=fVlLd4KtnLpF8Xfiq6WuhPaM93l3zD0NcBsP2nYPsCtQDFuYrDwevKi/OAXOz2NWJP2AUuGn3lk42an9LYOKwP7yYgrsCR+uhisYFMh04GvQ1e/IrUYsJKRcU5QkAjWcqRSR/by9J+NSCKbdyd08g5fOngtVY0C8KLefHjcnEwY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754601418; c=relaxed/simple; bh=hVmO1mXfYScEIC9DCreeKf4cE/D+CuTSXXgUR9zbjAA=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=PDmBxsZ61iRfzxopKB5pvOs9W5Idiy5sDtQRTp7Yqi9HpRFG5V/pqSYroX9zXFjZMv5FxXViMEvIvXTQ8Xwmwn1I10w4rsrRxbjjoEAirlUDPhpC6Ovc98r51cZ6Qib/1aI9rKC3M3TUCKRQBJUqhAE+0/I01QN9dIogfZ5x7BM= 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=K2CSc4BP; 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="K2CSc4BP" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net A2A0B40AD9 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1754601410; bh=rHWEDvv2LL6zewZlA89rUn/FMk+/6JqzsmSk7xj66XU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=K2CSc4BP9+fe9N9Xh+xNfEf8wL/V1wCVbp2bpT5v9I3fKLcgfDp9egwoA4BXmT1Am 9qVxiginp2ulT5vxe2pLfhLMydHlo2cpE3wkTe1xHYP5ojxGU/EboPRgHqsAV190fH e1r/gI/elSBm4hXfN+nk2vPAiFCgT6XxXvV5w4os2dG+HQgIqx2a0iEDV1jblFbnuU 9QyoHlMe/ctSJL+I1E/BjvkuB8/kGvBGTiBOM0rMGrNk44oeya4mV4nQfGQTQAECVS znbEnL5EAa306fDThdJjJL8rnHujVF8LWpKFpfQmB6xLNff15GDlJjCzBmgMMhvrpq 6zzUrLvEQqU0g== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id A2A0B40AD9; Thu, 7 Aug 2025 21:16:49 +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 v2 01/12] docs: kdoc: consolidate the stripping of private struct/union members Date: Thu, 7 Aug 2025 15:16:28 -0600 Message-ID: <20250807211639.47286-2-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250807211639.47286-1-corbet@lwn.net> References: <20250807211639.47286-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. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- 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 05:29:30 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 7FF4F2472AE; Thu, 7 Aug 2025 21:16:56 +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=1754601417; cv=none; b=ovp9lNaig+D5ZwTxvzcvaeDSQPygDhm6YHGdKiSN14RCC2duYQ0A2dEQc4o0rwN5vokMnBmq9tX5d/1P65bZT+ogyhqeQziiomY803vTSOqAuPq8Ebmqk06mMxZpsGkUR0OuISFW4q48yZJcyZfEpgqP1neqw0shjDNKGfaUdyQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754601417; c=relaxed/simple; bh=tbMgGZpRaCjDP10FLbn1GnJCo6mIb1HOMV4bFmHd/vE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=RpLTIH+xGYDai0kKxsn5jbif54QYlrng7J6qXyHGIT8TK9S0mD3uy+eDqHe/34Z7OiKy9w7GAlP+sfuC8BdD1i+oQVyvKgqytBbhACBRNVrMB+PHrVot+NyKf7kJyE6Z14g4QsOJ3Jw7k4Yt2//fffWTEb1GGJClappxwvyBy1M= 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=Gy4er/TP; 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="Gy4er/TP" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 3063340AE4 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1754601410; bh=vmO6d44uqcnUzHl4fvpCkwQ1jyHoTC/0aJaJguQ+Vi0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Gy4er/TP8mnDA+nhURdW09+yubtp/pbFARAZ+d28pwygtiTYJVgSau3NOuwiU7bv8 uP3GldwgCR3opXiUWIr4PfVmGQdQTOWZPs4fPAo/E/wuhXZa0idWMJVMkPrtqFrxqU w/Adr2Nmyn/vpj3y3ATwKmcH0viaLi9SxyCYTAubZtUI00/IfQvmyGmq2BoQAvpHhL pLN4nLRNoF+ywpr8EhqRWV9P2ayY4eag0Iq3xMpiqOPOryZLRSLFqY77hsTQQMkLOs xqBLtXZsM4IwVVKt5V2bkeCNnUZ12ZeqdjAig0dXFDlYqF2Vg1iRuScUETGU5ACbxq wFo2VFtOLq4Ag== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 3063340AE4; Thu, 7 Aug 2025 21:16:50 +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 v2 02/12] docs: kdoc: Move a regex line in dump_struct() Date: Thu, 7 Aug 2025 15:16:29 -0600 Message-ID: <20250807211639.47286-3-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250807211639.47286-1-corbet@lwn.net> References: <20250807211639.47286-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. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- 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..aa6d11bf29b1 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 05:29:30 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 6D1C1253934; Thu, 7 Aug 2025 21:16:57 +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=1754601419; cv=none; b=Jagm21r6FSxwxbuCuehp87Pc0bbgDNDPF7TBm4lCcKNwHweXaZOaV5XIcKPAaucbEgyajEfe5/yZrE+wsgXCIXRFj3hJqLuCYzMRneoRPMAlYQ4CwTdWyiq5YGOaJEgJdND4e+Y/x4mC2X9XCNLaoL3KKmdJBBdtEQJ7OkrVNfA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754601419; c=relaxed/simple; bh=L2cDRRPB5aff3Em7QzWZf/GRyXBTUFvU1Z5hya/sLok=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=paCCadssNYw/FGXCWzbMSHtLBCz1SRB8IzO6GvAhRgaoYdcC9QzXEftPoLZZaNSlV5FASBD0V/Kzzo4zv0Hohm/ba+DERyy5KTRWFx+mOs0b/Sj0NcegJwKZ3/RU9rpvcn629J/3+qQTsfuI7H2/S2mOPTAU5kmsXGg7m0faHlo= 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=sGHV8l5/; 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="sGHV8l5/" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net BC6E540AE7 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1754601411; bh=YuXq70gYDsDxuz2bttxrJmH0VnivAUsKGyBztKXkuug=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=sGHV8l5/Rk2e+s7obyRPNjPZu1sjIXq0Lf8CK3psAherICZ84m+bSAOsI1kwwVKP/ 10U/lQg8Yg8jQzl96gdTdq1EP2qJjAnMX4hVKxUd2Rq95dYg/HlZAGjkB85iULYgus AjBA2tZzTHLgiSfV5Z7zawhQaCT1l8uVItwensWrgpW6VFpmD7NhvnxQQkTot2GpSv 6bRBjn2AbKGM6Y9uf5wIwNls3MzFzof74SrDkxp6wH/Fnfi+J9GPhcLa5m+nHIeMhG S1MMttXkPF9dHlz9ocLwtNbLKAswMcN+argwng/4S1KCMV6RDXT2xghez80DYkrkiE 44W2tLeXrM/TQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id BC6E540AE7; Thu, 7 Aug 2025 21:16:50 +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 v2 03/12] docs: kdoc: backslashectomy in kdoc_parser Date: Thu, 7 Aug 2025 15:16:30 -0600 Message-ID: <20250807211639.47286-4-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250807211639.47286-1-corbet@lwn.net> References: <20250807211639.47286-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. Escaping of (){}[] has been left in place, even when unnecessary, for visual clarity. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index aa6d11bf29b1..14ded23f11e0 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. @@ -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,7 +428,7 @@ 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: @@ -443,7 +443,7 @@ 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: @@ -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) @@ -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,7 +1476,7 @@ 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. # --=20 2.50.1 From nobody Sun Oct 5 05:29:30 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 6D220253F07; Thu, 7 Aug 2025 21:16:57 +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=1754601420; cv=none; b=ptxSvd3khAAv/jdgqHcbhFxfmeK2E3DMr/CqAAstpnt3+53QQcAy3CxfHHbCNFrqJBvaWq5m2n9nhB8mL9BHPwLrm+dE63dCR+leHtHe2C7Dg0i3XUFHYgZZpgPgPCe+/vWPCQXgppio6Xdgq/9R6u8oqmGtKP68YgCBifCoW/w= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754601420; c=relaxed/simple; bh=Y1JPVdkW0ZuQP886EKwdKHpIzJNb8pFUL9NaRfcXCBU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=bcQZoTRButwpEGN2xsBWiT0UUlN1OjW9jVIvycss3iSfVqaHC4NVCYPvM+wO8jX48j6Yv9jmCcQeRJ6xI64OZGmkC9RE6hzFxb0vGfdkZNUBOFWzyRMpz0QFbuAtS5PVDNaAaCLcEXmH104AI6s+rIwTtVubFwGJoVIBvgsJbQs= 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=Vtn+BCQC; 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="Vtn+BCQC" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 48CA940AE8 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1754601411; bh=4rZUUE+B3JLh436Onn3GcH+PrFYpZVIc5JOehAf7FJQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Vtn+BCQC9bGoqobulvpWyMloj6ggvOlkTcWgY82wbHXoCVnsWblF68V1XGoHyF6rb 34IviCh1ECSwhehq+zRSW1w07inHeHNiTzPS7zPG8WQ7xseNYya1Ywk0VGq1i+vurX m67iw1IXL6DYzCyY9CqXf2QEPZ40AGcOhvn1v9shLceDlA75SnQ4HXssy1ALE6+CvL UzMBk48bmo1L+kDBOszRjk34MqkR1XEK4r4av5zneI6rE00vblf4j1BWGIFOt1dLk8 OfH6key99O2PIsMdEtLtp2SIcO+GAHswNlf/0Yy/mS8LA/064AXuZjicuc1l4PnrZ6 uuCa2cm9N0zvw== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 48CA940AE8; Thu, 7 Aug 2025 21:16:51 +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 v2 04/12] docs: kdoc: move the prefix transforms out of dump_struct() Date: Thu, 7 Aug 2025 15:16:31 -0600 Message-ID: <20250807211639.47286-5-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250807211639.47286-1-corbet@lwn.net> References: <20250807211639.47286-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. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 179 +++++++++++++++++--------------- 1 file changed, 96 insertions(+), 83 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 14ded23f11e0..3d007d200da6 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 # @@ -578,91 +667,15 @@ class KernelDoc: self.emit_msg(ln, f"expecting prototype for {decl_type} {self.entr= y.identifier}. Prototype was for {decl_type} {declaration_name} instead\n") return - - 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 05:29:30 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 BB28725744D; Thu, 7 Aug 2025 21:16:57 +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=1754601419; cv=none; b=T8rM0rAAi37FwSE7lKb/bpNi+BItUskQ6jsxAvnHgh0/3U9qULURC/ewrn+auARul8SfI7tsFfep+LjizgHb1YPS68HHCnYZ68pkhE64RkukCUsrl8cFA9xu8+sLowNk1K69eX3xyEv+js6aQnW1WFP1EAEx+louWsQrJTrPuyc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754601419; c=relaxed/simple; bh=U6Cdb2UXHVXgM89ENeSInYghrH/875aBHDVu+2iR/ng=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=iWuF/dSba7ZPNKianBPixFFh0uKVt8tQ7m8CAcKJH0ZgcmLcdpuQhcYGKSSM8dSvyOma99/H8Zcdq1RefxzMsL6wN8N+DXNwJ6T20Y30bcSuBnDSWKLF2VaAZLvu98DJe2Svn2BXw9wHKQ9fgAUvmiK+BRXVqMg1N3yQHmdTHFw= 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=kF0kF6fj; 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="kF0kF6fj" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net CDB5940AEC DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1754601412; bh=gWMBuOVlujIfTt07LRrVZBm2bcVGPhHFFpzO0WwZ40w=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=kF0kF6fjwrshWeKR2jxa7d/6do1K8tCf+hcsvTdTQVbcxfzAg+S6+BOXNzs95TTNa ppcj5m7uy6UtWhSexRDDQBWB9jQposU6+GPBcoNWxmM8EjJp9BspoOfDv3SrEHYLTT 4BlIIMGSMpxGOHrUQVIqWjUUJcp5XOwftvBNuodevf+JEmF5lgGtUF7QB15NYqcTma buniifLCSBLfC3A23y4LmKPHcluvzXBA6MJxEE83o0cmN+uxuiY5MRTPqPGVxaugSn fzU2OhYH0CDeCH16LNTI+EgRmll1XvngZu96FnsWZX85k6aCN8qkE7hRXhE3itnvFA Vi9xV4V6unVwg== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id CDB5940AEC; Thu, 7 Aug 2025 21:16:51 +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 v2 05/12] docs: kdoc: split top-level prototype parsing out of dump_struct() Date: Thu, 7 Aug 2025 15:16:32 -0600 Message-ID: <20250807211639.47286-6-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250807211639.47286-1-corbet@lwn.net> References: <20250807211639.47286-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. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 43 +++++++++++++++------------------ 1 file changed, 20 insertions(+), 23 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 3d007d200da6..ab896dcd9572 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,34 +636,33 @@ 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. @@ -695,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 05:29:30 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 BB21F256C6F; Thu, 7 Aug 2025 21:16:57 +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=1754601419; cv=none; b=GhVckDg+hlwyHuksypVQ9OZyZPFJ1c9Uw7bb8Bu6iPOXRhZ3W1GyXzwxRjlrnEthnU8+ZKX1m718BHIntGO/ngkYwXWNOxVHvnfzQsJAkNIeNsHHidLN2udA3td2k3ayedTyjQeHmeBJCIptvBIkKFPtnUFeUzEHP8G2+ts3qWI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754601419; c=relaxed/simple; bh=N5rIVFjF8OXnuuACRtghmEIhy0e0sl7T4fPAn/1yutY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=YpS7PgHCIFZatpNjTQi6Q7sTCnAKiKZZ1gAiRVHCtc8bT6t+580GHqSeadzti2+zyZZbWpLafpFdUr9VOQboH+KS7NH9kArxrj7T+bPVL2mHHFF7LlCJlgU4+0Ia1sk8m1yjaPHGegFLDdp0fGEq7GIj83BIdfqxHP0nxyS9+4U= 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=DLmIb4Rt; 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="DLmIb4Rt" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 6139240AED DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1754601412; bh=k0raakv8o00nkgtMwQK7Y4tf/xXq67ohe7aQZ0MsAag=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=DLmIb4RtENxOvp0X1oW1VcH8uZxLTWyhr/fkyyjlZBpbhnChX9SKxJ6gKPu9X5swS BNXbp67CgG1otwbYNlEy+ZALYADHzlhFdOVP2vcjWLBHcRht9b4E3hILc7kbdTT9HW 8dkYUy+WWQdN0UDq1Cd9yrQ8/Ouzn4zb3G+oF0kfCf0s+DDT3RUTWx8zts4u/NlfDS QZuPmxq7fmmAJQdu3SrnPjvbsygsM2iWE7BphCBIRep5GaJ9iekzra6y0Bm4M+ewiH dxPNTUFdDfO2AgMUhpVhw9wE8Zdch0dVL9jBsi15sCQT3kMNGHCmvMosgm2rG7vDeG aTYFMm0Dq3KbQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 6139240AED; Thu, 7 Aug 2025 21:16:52 +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 v2 06/12] docs: kdoc: split struct-member rewriting out of dump_struct() Date: Thu, 7 Aug 2025 15:16:33 -0600 Message-ID: <20250807211639.47286-7-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250807211639.47286-1-corbet@lwn.net> References: <20250807211639.47286-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. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- 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 ab896dcd9572..fbd7f6ce3360 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 05:29:30 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 54B2A25C827; Thu, 7 Aug 2025 21:16:58 +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=1754601419; cv=none; b=EJZci3OQJAjse9sPxc5xm20YJrHar0CqX+PkZSEHBigLr9ZcAt8LphpXSxDmTpBnn10blzwz9a/e6FLimz5dUd5Km3De1OGe3cHH5g38dhkc7ntivcKPW129H4Zr0pIIxlgdQfwvs1oc94Jc5+YDgYYLm/xbTTxa37BaKVdGDqk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754601419; c=relaxed/simple; bh=yinGlBpie4HuwDcmTLO434pKDF6hqOOdlGj9uA+y5Hg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=rbbEUJIskmvSwNjbVM7Ny+9AJUhsMzrtpZwZEiMxUF5EmpJIsB8b6H9sFtwe4bFikZqkLapVZsQUgs9AMWIYLdmkUf/Yel/zdy5gsJr3Yi9Y/oG9CwwXug8AporjJQY0NFa0pM0XI3iqAlkFDUozSMU61ySNg9OndlAN9T3bt38= 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=FziolT9X; 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="FziolT9X" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net E44FE40AEF DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1754601413; bh=MmGVKremYkRJqBzecc3T13fDBxhjQG5SuE3oGA2LXdM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=FziolT9Xapiqa/Lk1h4W0BWrcclG2WwUFAnsIhyq5oKt1uk0xT4IlsrbF7aDPu1Hw 24juoFZJs109NqqxftBf6ncmA+F3Np9GBWDNwE7O+qqXwr7b7rSs0na+wH4ftr92rv pjc/dS2aYhYzhDEe9/xmg9nGoibFsgikBT83K1o9GO2aeEMjjsaB+EiW/UnHbFkZjL cGXHSpm2jkuGQJttBr/6NSnQCzr1MrmiCZ1p3woW5JtWOwtHJ7gX2LbBKNd7eRwzh9 UEQHj55g3NUBqXHOcu1G7IncgCOeCPeor+2choBWvOs/IcrPcZnQEaWEF6sXOUNGVo FtvqPfGwARq2Q== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id E44FE40AEF; Thu, 7 Aug 2025 21:16:52 +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 v2 07/12] docs: kdoc: rework the rewrite_struct_members() main loop Date: Thu, 7 Aug 2025 15:16:34 -0600 Message-ID: <20250807211639.47286-8-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250807211639.47286-1-corbet@lwn.net> References: <20250807211639.47286-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. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- 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 fbd7f6ce3360..e11f3d6e9469 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 05:29:30 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 1D91525B1C7; Thu, 7 Aug 2025 21:16:58 +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=1754601419; cv=none; b=IdhHK/quoueskSaeg2a31uIpJhKtydeSSb/io7vM+7YuRPHxNP20afmBWCxZDILz7B/s6SJRQC/Y3MSIAY53JOimxrYt82XQuKDJJa0MzxH+cPZsnyfgjhV4Wy3TiH11t4IT2XuJSoPwfWC2k5jBXx6vVxlprxscnVx1EDnaAQk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754601419; c=relaxed/simple; bh=OttkNfFB3rq2l5lDSJzL3TNmcfpJs1eRTZkzGTeq7EI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=sw+L20Gc3cOeGW5YPUQUOh1k5D3OyATrZbzzOcmHVyVfp90CzhJwAKqRB0woSXthx4XaM1DYR+t9zxtJKLb8sZmkUzAe2+8owSj+Vtrszlm6V2/pz+sOkIbL4e4tUJJl0X7PIpqaXc8OYR3rWSrBBUsesmvleRogi2bzpSwXoSs= 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=GH/rzsIw; 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="GH/rzsIw" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 77D7740AF0 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1754601413; bh=H8s0gCkWKetxbMm7vsp83FemoWM7FDJeSxCXej5rgdU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=GH/rzsIwbC6u7ZDqo7DkLt8VZWI+mIsW9Wt4E7xLTtkGi+ALS1Xyk0StMjC/Tfp49 xIOVHUWG/l0ENwXR3gwu+T3+Bj5k7NCsO4sn/GqLIdabiTcF9rBifsv7sPJFM7P1YK PREpC/JcCB1q/6ng1mwx4ztXWpCmGRq3lSN5JsgZ1gKPsrxryPImCu0kwe1kDzrrlS WGVgE01chxiCJU4giRU7VUBwrqZeL5G0GlKFHdqd/5/PT7lMKiMkIL/3uCfxzuJIgx cwzVqNrurGmcKrLzpj9zT9Riejm+6icIcse+x1pwPhpfMsIJtmUk0ChCh1ElTwTLPj 4SI75AjX+GVjA== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 77D7740AF0; Thu, 7 Aug 2025 21:16:53 +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 v2 08/12] docs: kdoc: remove an extraneous strip() call Date: Thu, 7 Aug 2025 15:16:35 -0600 Message-ID: <20250807211639.47286-9-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250807211639.47286-1-corbet@lwn.net> References: <20250807211639.47286-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. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- 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 e11f3d6e9469..0c279aa802a0 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 05:29:30 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 8144326CE1C; Thu, 7 Aug 2025 21:16:58 +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=1754601420; cv=none; b=Dx0zYLErBKhoJmfgtOceorpwq3bRX4SxQSBC7fmsSIHMeyEmEGuOJjeOBfbMAj38WCzNxU6Vavp2qTGGDMBrjE7ZQVhCJXTP4UAOBjmf9PGLFIB+GhrEEZizSLAZpgUvGxcGdQewNhNDFHSx5rbKCg1b2tS3b79bMu73A2q321k= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754601420; c=relaxed/simple; bh=UataK2dH+WS9Ga0PirdCnTHcjTjTrYaaKiJkDBGN1II=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=uLrBsTfUcMlw0F+mc2KVjvu8Yl1BlUOAqwkaaUqUQv50fV8pI2ogBzlbmgm/qdzsbh0dpWoMKvV5aLUQRAQcqz4/uni4EtwIAVeOqJBC7loX9gXABZ9ZUZ2vN55s2gVvFGNWeCd1DzbnqFMTqjLQqll6DLJNaXU7tw7/2GQv46A= 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=O9TvI0v4; 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="O9TvI0v4" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 0D1D840AF1 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1754601414; bh=cRTibWquOyDOZaMN4U55xfQZDUSokjnEvoTYB0ZSrfc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=O9TvI0v4RgTtAVquWuSerC+VLTJeMz2pRy6fO0iW68YFYIWF5bQOdi3eRxAVgo+xk pinsovL793hKqMtT/6375X+6qrPwB0+147eCq38AmqlJkcGGOi7ANyZV0jz9pl5F7B so+OX6/CojucfQXuwJ1KUI23itHTFpEcyoH0NfrKmeVS6mzL14rj/hGVgndoPTFWFt F58iu2CeLCd64IOyTXZ6L2u6hlyJKFBeP6XlL9Yx9nKgCj2SvuX9za6d3j65olcioN j7idBTr/TGLJaKTemW0dzHnPVeL1SydrJdyD8rgVgHgNTP4zKxNhY5fnegEh7YFTSc 3CiTZPb3hIMFQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 0D1D840AF1; Thu, 7 Aug 2025 21:16:54 +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 v2 09/12] docs: kdoc: Some rewrite_struct_members() commenting Date: Thu, 7 Aug 2025 15:16:36 -0600 Message-ID: <20250807211639.47286-10-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250807211639.47286-1-corbet@lwn.net> References: <20250807211639.47286-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. Reviewed-by: Mauro Carvalho Chehab 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 0c279aa802a0..e3d0270b1a19 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 decla= ration + r'(\})' + r'([^\{\};]*)(;)') # 5: Remaining stuff a= fter declaration tuples =3D struct_members.findall(members) while tuples: for t in tuples: --=20 2.50.1 From nobody Sun Oct 5 05:29:30 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 C3D1326E17D; Thu, 7 Aug 2025 21:16:58 +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=1754601420; cv=none; b=q0XUjerODnPsnLy+0F73bToMRoFGAsCaIBFjmg71D/x/m7VlItOFiKI6dBPSwH+lui1sBjF+TSJpZUVWS7Vc6ICrSNyj8r3wnjBV6tGug8erlgoNBuUloGGbo7Xq07ea0aqnOitMiQ0Qwq85Vg5kC9jgp3d8lo6PiXXnxRYGHys= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754601420; c=relaxed/simple; bh=KqRBDuRd56N3m9KxKv3azQILGxVKC/1No6Zj5aBTqro=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=l+q6tcIQDmIgwc+elqCFYAdKlLFzarcg66CCqSg6CTBtDCpoEHGep/qxNnZ+W6jZCrTdvXBHQVUp/edZrzn28E1K7nIV1s5ghrFvvg/FLcpEz2yUYyw6JVawhpAfHHbX05+2EqL4+l4whRA1gnTvdB8jXOhmXT4wThubWkzw2hk= 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=QHlskJv0; 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="QHlskJv0" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 8F48740AF2 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1754601414; bh=tAb0bk4ax5qVarJrbCOpaj+1ZBbHDgd+H5S0UrhGMBY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=QHlskJv0XQXyzagwfoEXnuA8pot9zs/3iaFHj4iQkErHyu/yNaaed4ZdJfGe2Voxl Cg+vU24IE7F40npOBpnLaOl4+cOOjL6AIoxTlzqkrVeRILaBuQNR1it/flL1i6MS0N 2DkbAq1uJaYteiLh0+L3Rldtf8PfapMmg116j5iONV/8R9TeC9N6z+LJtxI+rH5P/3 WQL56x6FP+8gOmXRE/6k925aePhIbb8bVetMvMDBTo6eoEpdeTyCrCpKEQguwowppe N7bgbJFLpRW7QS4UvSusaO+FZQVScpFGq+tHPHnbtFPd1kR/h0Zt0VMCM+DZtTwsfq THL3N4ecYkZcQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 8F48740AF2; Thu, 7 Aug 2025 21:16:54 +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 v2 10/12] docs: kdoc: further rewrite_struct_members() cleanup Date: Thu, 7 Aug 2025 15:16:37 -0600 Message-ID: <20250807211639.47286-11-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250807211639.47286-1-corbet@lwn.net> References: <20250807211639.47286-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 redundant checks, and generally tighten up the code; no logical change. Signed-off-by: Jonathan Corbet --- scripts/lib/kdoc/kdoc_parser.py | 86 ++++++++++++++++----------------- 1 file changed, 41 insertions(+), 45 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index e3d0270b1a19..b3f937901037 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -673,73 +673,69 @@ 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 + dtype, name, lbr, content, rbr, rest, semi =3D t + # + # Pass through each field name, normalizing the form and f= ormatting. + # + for s_id in rest.split(','): s_id =3D s_id.strip() - - newmember +=3D f"{maintype} {s_id}; " + newmember +=3D f"{dtype} {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) - + # + # Pass through the members of this inner structure/uni= on. + # for arg in content.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): + dtype, name, extra =3D r.group(1), r.group(2),= r.group(3) # 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}; " else: newmember +=3D f"{dtype}{s_id}.{name}{extr= a}; " - + # + # 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 05:29:30 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 5FF2B273D79; Thu, 7 Aug 2025 21:16:59 +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=1754601421; cv=none; b=j2hrel07lOo214GlCdMZHxQ+yLXKSGxhQ8XJjZp3U4TcjrmEu2qM6OPDQ+O/zax/dGrJ+HJIuJm4vOVaG2eOW+DUZL63ICZ0mYMyRvqJC27IuerZBd7TbfMFIdIIkpSVx1ETGsoETuMP1z4LjwKbO8l3/93fFxRspcYqS37nCPw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754601421; c=relaxed/simple; bh=adH7OXl+otzNFNzoSik5tKElfx+kwuSo0U+fRjSy0L0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=uPH3z5+zb3Cw4EaYeLAHyOwpSf7v3pV3RiE8Y2TBCAM5JXfdlOBz/bHyDYVkIxuj+kUTrilNYaro2Ock2cupnzIwH74tfRon93gQ/oShcte7QvMDhjbTqZaDkoF45isTfign3n4oMESmVa/htVvDdsKXJ8gTNzGotktG8cXQ3os= 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=T0rRNTbW; 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="T0rRNTbW" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 1BDE440AF3 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1754601415; bh=muRusV7g0EhklNFUmiNLJ9yssnHmtO7n6vX21TF1FXI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=T0rRNTbWJli1JV/gXUiflnGsBZeoc/tVYaBmPiRRPPjvBkaD5fIMnH5yeoA+HgLwS Yg9iFZEsthRqMMiu5+8iifSc+uQAENy65ROEsR8Ho0yYGhKFzkj2dULn82eiKx5PVr QXVvnK4hzZM+keVKEpA2QlWJHtFizj1B62+PEWxymFO11r9SPgqE1kqO3mz9kVWW/P Bw+WpHlVRvtq0fOrEH531S5vaKikza1n0nQOI/NqZxfzfu8pDqWEizrYD7T9BhvydR SNB1Eum8v+3tWOy5q3oYdOfl3tKKRbn7+QU89vWtIwF+dhAsIrqULxIZLwoF2vZzK4 ZzcFMy+DF1d5A== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 1BDE440AF3; Thu, 7 Aug 2025 21:16:55 +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 v2 11/12] docs: kdoc: extract output formatting from dump_struct() Date: Thu, 7 Aug 2025 15:16:38 -0600 Message-ID: <20250807211639.47286-12-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250807211639.47286-1-corbet@lwn.net> References: <20250807211639.47286-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. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- 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 b3f937901037..878fbfab4ac7 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -739,6 +739,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 @@ -777,42 +813,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 05:29:30 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 A758B2741B0; Thu, 7 Aug 2025 21:16:59 +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=1754601421; cv=none; b=Yu1hv4CaQxW8m/FwFtTi7iGXKdJ7iD2ZiiXz+3E5PjPlMv7mQ4vi+cPMHGJ7LE3dPhOy8U8fFM7y8yNJh3VJ34cCBplOFJy8DwMJtyRigEzoIeFJOjsPOouc35jKMzQ5RB5fz16NxqWCriJa9SSIBEaYqsT0jQavqVV/mfMl5XA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1754601421; c=relaxed/simple; bh=Atau+QLjGuOfyYM2kTyMv5X5+6yarKGZzvGs4vVXSdI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=FSTE1PBtunpDXH7ys7ITIvioUPiGqGTDRYCU/z7DkHssqzXU5j5wd4hsozeBqsx047Ve2uzY+xKZ+BbUilPeEuxC2f0I6xOHuWFTy+BpKv7pukDtk6wWpYSDCjxhFkTzPuJMGjMtlDVmKdEPF7V/BNVNDp/FhIdSszWX4kOf61g= 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=rSraMNF5; 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="rSraMNF5" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 9D01C40AF4 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1754601416; bh=49DuByfCp+pk3uQ5bmHdgqLWb3lRGAoir3iVBpGDYmE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=rSraMNF5JnEFatxIyNggjj2udIvNm+FORQnqnGy6Roqx09a4MIb/T85LnnZsAKZAi KURvV6jMX8bfkQCpif+6n+21UoHn2LldjY6fhDBERi44+dFdvuFBcJWJ8X84BB4Bxe 0szvek3MfZXxMvZ+zwx5BxXa0nwe9uR6yA1pv55XYclmTI39LdbIPLmQM76sYNQL7y BmmuMFpG9PWTH3q252pXrcbqVuXuZD1EN0HbqyeT8b5QGMqKRaT8kC8DEPae9/4cq1 GRjGk1SUokJrcEfy6UX19yeW2NHVs09W2i877hY3AY3ESuetAvpTAL/pOtn+ZerlRQ HnC8HcfWJM/qQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:4600:2da9::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 9D01C40AF4; Thu, 7 Aug 2025 21:16:55 +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 v2 12/12] docs: kdoc: a few final dump_struct() touches Date: Thu, 7 Aug 2025 15:16:39 -0600 Message-ID: <20250807211639.47286-13-corbet@lwn.net> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20250807211639.47286-1-corbet@lwn.net> References: <20250807211639.47286-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. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- 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 878fbfab4ac7..9b21fb86709a 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -802,14 +802,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