From nobody Mon Feb 9 00:42:16 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 E797124A072; Mon, 24 Feb 2025 09:09:03 +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=1740388144; cv=none; b=s5TfLsfzB6jGGaB16RH5E8XqpJSuH/Kbrm77hDswXgK3Iy+TZdv1jbQvMQfIUCu2R7yr44EbfKld84GL3cfgWNwvnsOTr0KOXN9wyXLNDEcGeotq1GiZXAEI54XzC5Sui6x+LWHv4lNi5cccMp3nO9/EAg3nHUHEL+soja+Se5w= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1740388144; c=relaxed/simple; bh=6Zn2EKfxJ7Vkt0h37tV3CPuGsXDQh4z4UJHEkZnGtBU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=LXYAm26vp9fdFiW2pt/OJJPK8co34sq1J2k4zZlO9YEbnGRq+gVkE1WdptJnCQbilBExk/lQL7CHcfmOZq0niA1mXNGFfGLNg0Sqmo9ss/C3HpJiv8R0EDjj1jzx8ujSMq7j8tywglv5s9L4+8mmRyrLARM5mGf6SVnYm8b/wPc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=TZXKezhR; 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="TZXKezhR" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 6D213C4CEE6; Mon, 24 Feb 2025 09:09:03 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1740388143; bh=6Zn2EKfxJ7Vkt0h37tV3CPuGsXDQh4z4UJHEkZnGtBU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=TZXKezhRCWrPHNJ6trrfgHP5zygH1/n/1mrk7C9h6dRpwIQYALoe9HPRl3kFolPi6 ILEYi/S3G4F7pkxUFFt5NQ1enQ1lSgc3LUb4I6DAZoxOIxAB8yTTxOBtg3MDlSwF5p E90YkCVlwELulaBELLNNLTMiS6mZfmQ5pWBm1kmF9LaMZ79Z3apQrs/akaPlgzAyC2 nsljM2WMvgk7F9wazacDFx6lWN0Kx6VGXVgvOIaEgreRgb20DL6Ydovr1D0AHjO4fZ Gq3fec9mSHEHBBbI627I4uzyNuGk2gjFBOUtVazoJqMcAFpefsFu5TwoTZWCn9zX6/ TKTEvqW+ysbuQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tmUST-00000003p5J-2PsT; Mon, 24 Feb 2025 10:09:01 +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 v2 29/39] scripts/kernel-doc.py: adjust some coding style issues Date: Mon, 24 Feb 2025 10:08:35 +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