From nobody Fri Dec 19 22:03:11 2025 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 109041EA7C6; Wed, 19 Feb 2025 13:57:59 +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=1739973480; cv=none; b=pOI5E+WV2vHCQJxvV89xCxK8853W8f7n01iP4qOHhsE14fHz0c0tCeysemndcj4tYIQiJTlHg4DXp7Q2RJHjxpGOCrJ6+2PEqqJms9MrXAj1Mz20I+W9mA203IxkNyqS59UGIGum4az5faDvh8QHl2YT5ppWVyW1E/cz5f6Nj+Y= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1739973480; c=relaxed/simple; bh=6Zn2EKfxJ7Vkt0h37tV3CPuGsXDQh4z4UJHEkZnGtBU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=sXhTL2P+rm1mpxezFumHAH/9vlo8l6ngxCLYROw/5rs7fYUW87G/dCwvEoRdf2T0dlA8Cu2pjVSKQJi5B2cGhYZHMEp3ZJz8zKcIhH+IPJsah8TENm9lQvV1RBw9Wy5MyhgRdzhLDasz5x+itrd0r777CTdb6N46fXFlRIbrNP4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=DgDFeI/O; 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="DgDFeI/O" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 9B7B6C4CEDD; Wed, 19 Feb 2025 13:57:59 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1739973479; bh=6Zn2EKfxJ7Vkt0h37tV3CPuGsXDQh4z4UJHEkZnGtBU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=DgDFeI/O2NNbrkNTZzx7DETQlfdJh1O6gY8v1fE6wo/efX3cuwikAt4W0MF8rfjLV nQ5vbJp61d/b8mj32OVIfXlPfaf/a7UdfJEOC3szOJH5sL3EgaFlFBVIyGwg7v9klx /l+pmKWiDscEUcMO5sx6PLbLHQNzWyae3n7AAuMZQHEEdVct02UvZQP5WRCkNgOql4 9/+p0r8mwGDXj2SGqPyIqt6K0yp31wxmzMSPrUl/QJB/94MH3L3uUrzKMZJVIoBbZx WCNjotpdseScoPY1xwYmgl/ffAdDVSq5nNbdb0UnZ3BactZhPJJRMW3xHQj+InomvL qQTqBiN/jQpHw== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tkkaL-0000000H1jJ-0gi4; Wed, 19 Feb 2025 14:57:57 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [PATCH 2/6] scripts/kernel-doc.py: adjust some coding style issues Date: Wed, 19 Feb 2025 14:57:37 +0100 Message-ID: X-Mailer: git-send-email 2.48.1 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-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Make pylint happier by adding some missing documentation and addressing a couple of pylint warnings. Signed-off-by: Mauro Carvalho Chehab --- scripts/kernel-doc.py | 2 ++ scripts/lib/kdoc/kdoc_files.py | 4 +-- scripts/lib/kdoc/kdoc_output.py | 51 ++++++++++++++++++++++++++------- 3 files changed, 43 insertions(+), 14 deletions(-) diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py index d700451e9541..daae2b4f3307 100755 --- a/scripts/kernel-doc.py +++ b/scripts/kernel-doc.py @@ -90,6 +90,8 @@ neither here nor at the original Perl script. =20 =20 class MsgFormatter(logging.Formatter): + """Helper class to format warnings on a similar way to kernel-doc.pl""" + def format(self, record): record.levelname =3D record.levelname.capitalize() return logging.Formatter.format(self, record) diff --git a/scripts/lib/kdoc/kdoc_files.py b/scripts/lib/kdoc/kdoc_files.py index 957aaeaed7e6..e1ed2f6dae94 100755 --- a/scripts/lib/kdoc/kdoc_files.py +++ b/scripts/lib/kdoc/kdoc_files.py @@ -3,8 +3,6 @@ # Copyright(c) 2025: Mauro Carvalho Chehab . # SPDX-License-Identifier: GPL-2.0 =20 -# TODO: implement warning filtering - """ Parse lernel-doc tags on multiple kernel source files. """ @@ -127,7 +125,7 @@ class KernelFiles(): def __init__(self, verbose=3DFalse, out_style=3DNone, werror=3DFalse, wreturn=3DFalse, wshort_desc=3DFalse, wcontents_before_sections=3DFalse, - logger=3DNone, modulename=3DNone, export_file=3DNone): + logger=3DNone, modulename=3DNone): """ Initialize startup variables and parse all files """ diff --git a/scripts/lib/kdoc/kdoc_output.py b/scripts/lib/kdoc/kdoc_output= .py index 7aeaec884545..97ec671e0b6e 100755 --- a/scripts/lib/kdoc/kdoc_output.py +++ b/scripts/lib/kdoc/kdoc_output.py @@ -1,10 +1,8 @@ #!/usr/bin/env python3 -# pylint: disable=3DC0301,R0911,R0912,R0913,R0914,R0915,R0917 +# pylint: disable=3DC0301,R0902,R0911,R0912,R0913,R0914,R0915,R0917 # Copyright(c) 2025: Mauro Carvalho Chehab . # SPDX-License-Identifier: GPL-2.0 =20 -# TODO: implement warning filtering - """ Implement output filters to print kernel-doc documentation. =20 @@ -51,6 +49,11 @@ type_member_func =3D type_member + Re(r"\(\)", cache=3DF= alse) =20 =20 class OutputFormat: + """ + Base class for OutputFormat. If used as-is, it means that only + warnings will be displayed. + """ + # output mode. OUTPUT_ALL =3D 0 # output all symbols and doc sections OUTPUT_INCLUDE =3D 1 # output only specified symbols @@ -74,6 +77,10 @@ class OutputFormat: self.data =3D "" =20 def set_config(self, config): + """ + Setup global config variables used by both parser and output. + """ + self.config =3D config =20 def set_filter(self, export, internal, symbol, nosymbol, function_tabl= e, @@ -116,6 +123,10 @@ class OutputFormat: return block =20 def out_warnings(self, args): + """ + Output warnings for identifiers that will be displayed. + """ + warnings =3D args.get('warnings', []) =20 for warning, log_msg in warnings: @@ -145,6 +156,11 @@ class OutputFormat: return False =20 def check_declaration(self, dtype, name, args): + """ + Checks if a declaration should be output or not based on the + filtering criteria. + """ + if name in self.nosymbol: return False =20 @@ -168,6 +184,10 @@ class OutputFormat: return False =20 def msg(self, fname, name, args): + """ + Handles a single entry from kernel-doc parser + """ + self.data =3D "" =20 dtype =3D args.get('type', "") @@ -202,24 +222,24 @@ class OutputFormat: return None =20 # Virtual methods to be overridden by inherited classes + # At the base class, those do nothing. def out_doc(self, fname, name, args): - pass + """Outputs a DOC block""" =20 def out_function(self, fname, name, args): - pass + """Outputs a function""" =20 def out_enum(self, fname, name, args): - pass + """Outputs an enum""" =20 def out_typedef(self, fname, name, args): - pass + """Outputs a typedef""" =20 def out_struct(self, fname, name, args): - pass - + """Outputs a struct""" =20 class RestFormat(OutputFormat): - # """Consts and functions used by ReST output""" + """Consts and functions used by ReST output""" =20 highlights =3D [ (type_constant, r"``\1``"), @@ -264,6 +284,11 @@ class RestFormat(OutputFormat): self.data +=3D f".. LINENO {ln}\n" =20 def output_highlight(self, args): + """ + Outputs a C symbol that may require being converted to ReST using + the self.highlights variable + """ + input_text =3D args output =3D "" in_literal =3D False @@ -578,6 +603,10 @@ class ManFormat(OutputFormat): self.man_date =3D dt.strftime("%B %Y") =20 def output_highlight(self, block): + """ + Outputs a C symbol that may require being highlighted with + self.highlights variable using troff syntax + """ =20 contents =3D self.highlight_block(block) =20 @@ -600,7 +629,7 @@ class ManFormat(OutputFormat): sections =3D args.get('sections', {}) =20 if not self.check_doc(name, args): - return + return =20 self.data +=3D f'.TH "{module}" 9 "{module}" "{self.man_date}" "AP= I Manual" LINUX' + "\n" =20 --=20 2.48.1