From nobody Sun Oct 5 07:22:33 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