From nobody Mon Feb 9 06:02:09 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 AFFF824A04F; 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=1740388143; cv=none; b=a6cUdcRUpkRP0XQ99nYYln9bTwf7pUjoNilXGRUj8lGbZQ2QdlNWdjHxL/UXTR6YkBr7t09+sfPFbMjaY4z8AafSbNVgSRMvHUVBPmUk67NNR120/ITGcMDURHd7d094bky3vrwjcvv55+OoNgHHRKs13mumohWMOKMXFWMtwCY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1740388143; c=relaxed/simple; bh=f3hhbbpUGqP6w/O5kQrl+GO4MbXaX4mT/0fXNELBwgs=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=rbcNDnwPqdphLkudKh4ohvdfyjIAYQ+aC0FTs7FhK6s1ZffYUd0qSmxgBVGcoZxP8W4vHDK0Y05NEu7rHAWBmnAUVikYE37aYUvNimGpKFQ/toAK2mfiRS7aVmfQX+HNjs5fTx5Cte1dygm+/Xwv1jhXPc5MDahM/ofJeY438rQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=YB5y2++5; 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="YB5y2++5" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 42EFBC19424; 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=f3hhbbpUGqP6w/O5kQrl+GO4MbXaX4mT/0fXNELBwgs=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=YB5y2++5kEkhN3MH3+2K+mEfRgleCCW9kWxGhma3hQUC0VZ/gL9Kox4f/CKtMhEIh alzztNiReSngs4HEIkE6PUyIF0Bxjtrc4LnfroxsvDuGBul2/NlbV2st7NNK3QyX3+ E6MG2ZPxgrtpYec13cIC6dyYoayAH1uqE92peuQhsh45RcSpfTi/zXFGxIib1e7VPH eJprxVZj/1xNIBU1g7d4p87zu9S//C24QqibIov2hyqoyE0iXjDZHJX9ljpL0xTmAz Y8WOEvxOiel3YkGPcbbj9xkPGzXMid2FKF/+Hk8R3vvy4ysCGItAES82CONedw9vbF zGP0yGMItyclg== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tmUST-00000003p4u-1kit; 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 23/39] scripts/kernel-doc.py: postpone warnings to the output plugin Date: Mon, 24 Feb 2025 10:08:29 +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" We don't want to have warnings displayed for symbols that weren't output. So, postpone warnings print to the output plugin, where symbol output is validated. Signed-off-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_output.py | 24 +++++++++++++++---- scripts/lib/kdoc/kdoc_parser.py | 41 ++++++++++++++++----------------- 2 files changed, 39 insertions(+), 26 deletions(-) diff --git a/scripts/lib/kdoc/kdoc_output.py b/scripts/lib/kdoc/kdoc_output= .py index ca21cd856be4..7aeaec884545 100755 --- a/scripts/lib/kdoc/kdoc_output.py +++ b/scripts/lib/kdoc/kdoc_output.py @@ -115,7 +115,16 @@ class OutputFormat: =20 return block =20 - def check_doc(self, name): + def out_warnings(self, args): + warnings =3D args.get('warnings', []) + + for warning, log_msg in warnings: + if warning: + self.config.log.warning(log_msg) + else: + self.config.log.info(log_msg) + + def check_doc(self, name, args): """Check if DOC should be output""" =20 if self.no_doc_sections: @@ -125,19 +134,22 @@ class OutputFormat: return False =20 if self.out_mode =3D=3D self.OUTPUT_ALL: + self.out_warnings(args) return True =20 if self.out_mode =3D=3D self.OUTPUT_INCLUDE: if name in self.function_table: + self.out_warnings(args) return True =20 return False =20 - def check_declaration(self, dtype, name): + def check_declaration(self, dtype, name, args): if name in self.nosymbol: return False =20 if self.out_mode =3D=3D self.OUTPUT_ALL: + self.out_warnings(args) return True =20 if self.out_mode in [self.OUTPUT_INCLUDE, self.OUTPUT_EXPORTED]: @@ -146,9 +158,11 @@ class OutputFormat: =20 if self.out_mode =3D=3D self.OUTPUT_INTERNAL: if dtype !=3D "function": + self.out_warnings(args) return True =20 if name not in self.function_table: + self.out_warnings(args) return True =20 return False @@ -162,7 +176,7 @@ class OutputFormat: self.out_doc(fname, name, args) return self.data =20 - if not self.check_declaration(dtype, name): + if not self.check_declaration(dtype, name, args): return self.data =20 if dtype =3D=3D "function": @@ -327,7 +341,7 @@ class RestFormat(OutputFormat): self.data +=3D "\n" =20 def out_doc(self, fname, name, args): - if not self.check_doc(name): + if not self.check_doc(name, args): return self.out_section(args, out_docblock=3DTrue) =20 @@ -585,7 +599,7 @@ class ManFormat(OutputFormat): sectionlist =3D args.get('sectionlist', []) sections =3D args.get('sections', {}) =20 - if not self.check_doc(name): + if not self.check_doc(name, args): return =20 self.data +=3D f'.TH "{module}" 9 "{module}" "{self.man_date}" "AP= I Manual" LINUX' + "\n" diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 116289622f2c..a71145d531f2 100755 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -130,23 +130,23 @@ class KernelDoc: # Place all potential outputs into an array self.entries =3D [] =20 - def show_warnings(self, dtype, declaration_name): # pylint: disable= =3DW0613 - """ - Allow filtering out warnings - """ - - # TODO: implement it - - return True - # TODO: rename to emit_message def emit_warning(self, ln, msg, warning=3DTrue): """Emit a message""" =20 + log_msg =3D f"{self.fname}:{ln} {msg}" + + if self.entry: + # Delegate warning output to output logic, as this way it + # will report warnings/info only for symbols that are output + + self.entry.warnings.append((warning, log_msg)) + return + if warning: - self.config.log.warning("%s:%d %s", self.fname, ln, msg) + self.config.log.warning(log_msg) else: - self.config.log.info("%s:%d %s", self.fname, ln, msg) + self.config.log.info(log_msg) =20 def dump_section(self, start_new=3DTrue): """ @@ -220,10 +220,9 @@ class KernelDoc: # For now, we're keeping the same name of the function just to make # easier to compare the source code of both scripts =20 - if "declaration_start_line" not in args: - args["declaration_start_line"] =3D self.entry.declaration_star= t_line - + args["declaration_start_line"] =3D self.entry.declaration_start_li= ne args["type"] =3D dtype + args["warnings"] =3D self.entry.warnings =20 # TODO: use colletions.OrderedDict =20 @@ -256,6 +255,8 @@ class KernelDoc: self.entry.struct_actual =3D "" self.entry.prototype =3D "" =20 + self.entry.warnings =3D [] + self.entry.parameterlist =3D [] self.entry.parameterdescs =3D {} self.entry.parametertypes =3D {} @@ -327,7 +328,7 @@ class KernelDoc: if param not in self.entry.parameterdescs and not param.startswith= ("#"): self.entry.parameterdescs[param] =3D self.undescribed =20 - if self.show_warnings(dtype, declaration_name) and "." not in = param: + if "." not in param: if decl_type =3D=3D 'function': dname =3D f"{decl_type} parameter" else: @@ -867,16 +868,14 @@ class KernelDoc: self.entry.parameterlist.append(arg) if arg not in self.entry.parameterdescs: self.entry.parameterdescs[arg] =3D self.undescribed - if self.show_warnings("enum", declaration_name): - self.emit_warning(ln, - f"Enum value '{arg}' not described i= n enum '{declaration_name}'") + self.emit_warning(ln, + f"Enum value '{arg}' not described in en= um '{declaration_name}'") member_set.add(arg) =20 for k in self.entry.parameterdescs: if k not in member_set: - if self.show_warnings("enum", declaration_name): - self.emit_warning(ln, - f"Excess enum value '%{k}' descripti= on in '{declaration_name}'") + self.emit_warning(ln, + f"Excess enum value '%{k}' description i= n '{declaration_name}'") =20 self.output_declaration('enum', declaration_name, enum=3Ddeclaration_name, --=20 2.48.1