From nobody Sun Oct 5 18:19:56 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