From nobody Tue Feb 10 04:15:59 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (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 BC8372FD7D5; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; cv=none; b=FzLet2oon4YZGMioZPiy2fKItDFOQaUdJ7fBlsqshlDQcjNvtdSGl1wx4lTwNtMzfYHEXIUzPELrPsPCGVSxjbRRgCyfjJwPp6owKEeBtAXTMb7gQRGgiWU0fwIKMfE51gbkGjKVA3TdXl3ckCa07Ki3/jfTo51sOE0OrMXqss0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768839814; c=relaxed/simple; bh=tfVDmQ1gX9VG9PNgXAXt4hYgxcfeRlZft7aVQXVoK88=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=utUPy3G+YVmzGNmv5bzJHp/u36w+tjWGT2fZ47rkfDokVT0lWLCLNJNP+Lvs+sYtQSgzGzG886zf/3coEuUbPf7lvN7rH5laL3q4ZlSHZyvaz/ngdTOpiknLzWx4/+VIyDv703SlBS5gQVPSg1ILPY6MDXQxbNpnTYijXl8Ry9E= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ROCZdxLq; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="ROCZdxLq" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 3F8DEC2BCC9; Mon, 19 Jan 2026 16:23:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768839814; bh=tfVDmQ1gX9VG9PNgXAXt4hYgxcfeRlZft7aVQXVoK88=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ROCZdxLqd7TRMtN7NYdj0WL6tefWkBjzaduO1JD5v+6xy09BEGq+2erKGUgkWf+6G GUWPMTZ084Ng5YNv/wczwYTIFI3PHnyrBLX13lkKa0oB6Kvgxiv+nVNigBTrqEZnr5 u1WSFfu4pjPlch76mtdNIHMRcU7XmnGkjbFaz1cu/X76iJUfKLyXCeCquU4wyRMzJj 0p4k953VSA3dn5CH9qen/paM306PQf0Xw+KBoFqzQybrk4ZpaVHkmGwy1KQ2W0DKOZ nBb4VPttT0KvswKlGOPzwHyLm0S9XVC9B8yQ32Cm+SfFVW5d9WZxTxxPt6qWf4TPrV 1UgTG2pGyN7Xw== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vhs2O-00000001j2S-2ErO; Mon, 19 Jan 2026 17:23:32 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Mauro Carvalho Chehab Subject: [PATCH 17/25] docs: python: abi_parser: do some improvements at documentation Date: Mon, 19 Jan 2026 17:23:20 +0100 Message-ID: X-Mailer: git-send-email 2.52.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Add documentation for two consts and ensure that all sentenses will end with a dot. Signed-off-by: Mauro Carvalho Chehab --- tools/lib/python/abi/abi_parser.py | 33 ++++++++++++++++-------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/tools/lib/python/abi/abi_parser.py b/tools/lib/python/abi/abi_= parser.py index 9b8db70067ef..d7bb20ef3acc 100644 --- a/tools/lib/python/abi/abi_parser.py +++ b/tools/lib/python/abi/abi_parser.py @@ -21,14 +21,17 @@ from abi.helpers import AbiDebug, ABI_DIR =20 =20 class AbiParser: - """Main class to parse ABI files""" + """Main class to parse ABI files.""" =20 + #: Valid tags at Documentation/ABI. TAGS =3D r"(what|where|date|kernelversion|contact|description|users)" + + #: ABI elements that will auto-generate cross-references. XREF =3D r"(?:^|\s|\()(\/(?:sys|config|proc|dev|kvd)\/[^,.:;\)\s]+)(?:= [,.:;\)\s]|\Z)" =20 def __init__(self, directory, logger=3DNone, enable_lineno=3DFalse, show_warnings=3DTrue, debug=3D0): - """Stores arguments for the class and initialize class vars""" + """Stores arguments for the class and initialize class vars.""" =20 self.directory =3D directory self.enable_lineno =3D enable_lineno @@ -65,7 +68,7 @@ class AbiParser: self.re_xref_node =3D re.compile(self.XREF) =20 def warn(self, fdata, msg, extra=3DNone): - """Displays a parse error if warning is enabled""" + """Displays a parse error if warning is enabled.""" =20 if not self.show_warnings: return @@ -77,7 +80,7 @@ class AbiParser: self.log.warning(msg) =20 def add_symbol(self, what, fname, ln=3DNone, xref=3DNone): - """Create a reference table describing where each 'what' is locate= d""" + """Create a reference table describing where each 'what' is locate= d.""" =20 if what not in self.what_symbols: self.what_symbols[what] =3D {"file": {}} @@ -92,7 +95,7 @@ class AbiParser: self.what_symbols[what]["xref"] =3D xref =20 def _parse_line(self, fdata, line): - """Parse a single line of an ABI file""" + """Parse a single line of an ABI file.""" =20 new_what =3D False new_tag =3D False @@ -264,7 +267,7 @@ class AbiParser: self.warn(fdata, "Unexpected content", line) =20 def parse_readme(self, nametag, fname): - """Parse ABI README file""" + """Parse ABI README file.""" =20 nametag["what"] =3D ["Introduction"] nametag["path"] =3D "README" @@ -282,7 +285,7 @@ class AbiParser: nametag["description"] +=3D line =20 def parse_file(self, fname, path, basename): - """Parse a single file""" + """Parse a single file.""" =20 ref =3D f"abi_file_{path}_{basename}" ref =3D self.re_unprintable.sub("_", ref).strip("_") @@ -348,7 +351,7 @@ class AbiParser: self.add_symbol(what=3Dw, fname=3Dfname, xref=3Dfdata.= key) =20 def _parse_abi(self, root=3DNone): - """Internal function to parse documentation ABI recursively""" + """Internal function to parse documentation ABI recursively.""" =20 if not root: root =3D self.directory @@ -377,7 +380,7 @@ class AbiParser: self.parse_file(name, path, basename) =20 def parse_abi(self, root=3DNone): - """Parse documentation ABI""" + """Parse documentation ABI.""" =20 self._parse_abi(root) =20 @@ -385,7 +388,7 @@ class AbiParser: self.log.debug(pformat(self.data)) =20 def desc_txt(self, desc): - """Print description as found inside ABI files""" + """Print description as found inside ABI files.""" =20 desc =3D desc.strip(" \t\n") =20 @@ -393,7 +396,7 @@ class AbiParser: =20 def xref(self, fname): """ - Converts a Documentation/ABI + basename into a ReST cross-reference + Converts a Documentation/ABI + basename into a ReST cross-referenc= e. """ =20 xref =3D self.file_refs.get(fname) @@ -403,7 +406,7 @@ class AbiParser: return xref =20 def desc_rst(self, desc): - """Enrich ReST output by creating cross-references""" + """Enrich ReST output by creating cross-references.""" =20 # Remove title markups from the description # Having titles inside ABI files will only work if extra @@ -459,7 +462,7 @@ class AbiParser: =20 def doc(self, output_in_txt=3DFalse, show_symbols=3DTrue, show_file=3D= True, filter_path=3DNone): - """Print ABI at stdout""" + """Print ABI at stdout.""" =20 part =3D None for key, v in sorted(self.data.items(), @@ -549,7 +552,7 @@ class AbiParser: yield (msg, file_ref[0][0], ln) =20 def check_issues(self): - """Warn about duplicated ABI entries""" + """Warn about duplicated ABI entries.""" =20 for what, v in self.what_symbols.items(): files =3D v.get("file") @@ -575,7 +578,7 @@ class AbiParser: self.log.warning("%s is defined %d times: %s", what, len(f), "= ; ".join(f)) =20 def search_symbols(self, expr): - """ Searches for ABI symbols """ + """ Searches for ABI symbols.""" =20 regex =3D re.compile(expr, re.I) =20 --=20 2.52.0