From nobody Sun Feb 8 11:43:12 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 9D2F932FA2A; Sat, 17 Jan 2026 09:29:32 +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=1768642172; cv=none; b=tDZmVNXso5PzS/bHHpMml0jcP+kDFoFv9b7KpGGBS+P/jiQTr1ceSNaq6Tpp5iMw8jchweKFuLP38e9ktunILbC3tFKvCcMuqzR6wHQd5gIFM0XF9fu6CgoshAyRXJwCxLX8p08rBfgfxTkgPpK1cNnBjtcFInZ7IbqVlDAv1u0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768642172; c=relaxed/simple; bh=TCIDBeqflVUFZ2smOAiTOF7w3v48ieHVeu+24TcmIW0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=ooSAzu5ZV5zDNqpytaMFIEcnoAx4xjAokrBsNpfMXXOrqjHj5TwqHXNQFZpJykLCFRrPPOdvWKSEY0Y6c517x69F6St1uhYsGGzISFVsV3ih7FAvJ9j/hCZxYYe6ynqVKnn36nOV/Z/KxUEoELeV8zUXsoVY2tM00xjNkYOK2bQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=XJOONk13; 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="XJOONk13" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 1AD53C19421; Sat, 17 Jan 2026 09:29:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768642172; bh=TCIDBeqflVUFZ2smOAiTOF7w3v48ieHVeu+24TcmIW0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=XJOONk13XDg+Vh6MUpiG1UvbgkqgyS6CoxXIA28gsmmRDCPYHkQ4M4zkJLGZMKesg pCeCbVZxeXOiBaofjT0jiRr7rhro8nGVmNRUSpmTVtiAR4bMIfQG7FRKq1wgALFu0Q aidhMvDvT5FgvOA97rzBvkIJ+0JSvGZU7pwFJTDrGIENQopoiB5qjVqZFjZWaWczPR thzXfRk5uXXg7tj89hCYBlvJFz7+4dJ9dlWAPY+oieII1rKxvBHYxzAobwWBquxDLp sTRM1fDbcicTQrxHip7QVN/XhHsBoShNLz6mGNwYkzOv4dGQeZyFDRU7nFhThYA4d6 RerYLpykplLqw== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vh2cc-00000000fnw-0Hz1; Sat, 17 Jan 2026 10:29:30 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Andy Shevchenko , Jonathan Corbet , Mauro Carvalho Chehab , Randy Dunlap , stable@vger.kernel.org Subject: [PATCH v5 1/4] scripts/kernel-doc: fix logic to handle unissued warnings Date: Sat, 17 Jan 2026 10:29:23 +0100 Message-ID: <2de5f576f4ec010962e34d8cd1868c89cce910e9.1768642102.git.mchehab+huawei@kernel.org> 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 Changeset 469c1c9eb6c9 ("kernel-doc: Issue warnings that were silently disc= arded") didn't properly addressed the missing messages behavior, as it was calling directly python logger low-level function, instead of using the expected method to emit warnings. Basically, there are two methods to log messages: - self.config.log.warning() - This is the raw level to emit a warning. It just writes the a message at stderr, via python logging, as it is initialized as: self.config.log =3D logging.getLogger("kernel-doc") - self.config.warning() - This is where we actually consider a message as a warning, properly incrementing error count. Due to that, several parsing error messages are internally considered as success, causing -Werror to not work on such messages. While here, ensure that the last ignored entry will also be handled by adding an extra check at the end of the parse handler. Fixes: 469c1c9eb6c9 ("kernel-doc: Issue warnings that were silently discard= ed") Closes: https://lore.kernel.org/linux-doc/20260112091053.00cee29a@foz.lan/ Cc: stable@vger.kernel.org Signed-off-by: Mauro Carvalho Chehab Acked-by: Andy Shevchenko --- tools/lib/python/kdoc/kdoc_parser.py | 35 ++++++++++++++++++++++------ 1 file changed, 28 insertions(+), 7 deletions(-) diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/k= doc_parser.py index a9a37519145d..c03505889dc2 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -295,7 +295,7 @@ class KernelEntry: =20 # TODO: rename to emit_message after removal of kernel-doc.pl def emit_msg(self, ln, msg, *, warning=3DTrue): - """Emit a message""" + """Emit a message.""" =20 log_msg =3D f"{self.fname}:{ln} {msg}" =20 @@ -448,18 +448,37 @@ class KernelDoc: =20 self.config.log.debug("Output: %s:%s =3D %s", dtype, name, pformat= (args)) =20 + def emit_unused_warnings(self): + """ + When the parser fails to produce a valid entry, it places some + warnings under `entry.warnings` that will be discarded when resett= ing + the state. + + Ensure that those warnings are not lost. + + .. note:: + + Because we are calling `config.warning()` here, those + warnings are not filtered by the `-W` parameters: they will = all + be produced even when `-Wreturn`, `-Wshort-desc`, and/or + `-Wcontents-before-sections` are used. + + Allowing those warnings to be filtered is complex, because it + would require storing them in a buffer and then filtering th= em + during the output step of the code, depending on the + selected symbols. + """ + if self.entry and self.entry not in self.entries: + for log_msg in self.entry.warnings: + self.config.warning(log_msg) + def reset_state(self, ln): """ Ancillary routine to create a new entry. It initializes all variables used by the state machine. """ =20 - # - # Flush the warnings out before we proceed further - # - if self.entry and self.entry not in self.entries: - for log_msg in self.entry.warnings: - self.config.log.warning(log_msg) + self.emit_unused_warnings() =20 self.entry =3D KernelEntry(self.config, self.fname, ln) =20 @@ -1741,6 +1760,8 @@ class KernelDoc: # Hand this line to the appropriate state handler self.state_actions[self.state](self, ln, line) =20 + self.emit_unused_warnings() + except OSError: self.config.log.error(f"Error: Cannot open file {self.fname}") =20 --=20 2.52.0 From nobody Sun Feb 8 11:43:12 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 340B8332EB4; Sat, 17 Jan 2026 09:29:33 +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=1768642173; cv=none; b=OwyxacYervPF5ddJwI29lg4J2fBH4EJtesORxTJZNrglD1NUsYeUbtczGsQL4htMqk3Yvff+jsCYZQwsahMIho4P9dXd/MrrPGtyuDFK+TtKtXR1gpjwh/3NZ//5AtUqtTSp4DemcwRDR6l/btTjlreqpoLvic00uLQGvkKzNyc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768642173; c=relaxed/simple; bh=gswQgvIkCvCKkiNyrJA/gedBlbjViDDQyImQR0Lwtf4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Ao5yoP8Gb9NtSNVMfUUmfC/FTjumgbqYql+SshXlWIjO6i6Px32XvVi8dAEy/pOBDm8Zfsf6aYFf2c64qbys1CgRXdtxjrEhBUpEMQBlTOcG7Dqy86taKMVwz1Xjw65A3uzJPFtMJ3KqHwxgvL8uy9ONVtAudabC5uE/Cy+nWgE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Ytg0q7Sd; 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="Ytg0q7Sd" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 1E7DFC4AF0C; Sat, 17 Jan 2026 09:29:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768642172; bh=gswQgvIkCvCKkiNyrJA/gedBlbjViDDQyImQR0Lwtf4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Ytg0q7Sda8Jtsy2t6IOq0BjFLwvPDF54IHLZ9fCwaHf8qcu+VB1SinYReE8s8cJi+ Bui5o/NsgKTA4NJ7pzpT3NsDDN4YnNkfaAvJ5L2ybgxLZ+t6j2m0Kp8wuO9jPyUxod QqqZASSVpoh5yBGTC8rbE1Z9/doqBfw2Wsb3kHcFIsAXe4sSx9i2Ireu/UXakua0ty GoAv/HJMA9GistLkQSau04Iw0PfFTFj/H43WwGx+kPViEvWEv2YWYP9IqtlbO1e5e+ +7Mi+KsXD/0wF+55gJyFwCiWCZkdBr7FYEiStR42BSd96kuXddZOIV3oJJNXbMgg60 wJQOKnX9m4f9w== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vh2cc-00000000fo2-0OzK; Sat, 17 Jan 2026 10:29:30 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Shuah Khan , stable@vger.kernel.org Subject: [PATCH v5 2/4] scripts/kernel-doc: avoid error_count overflows Date: Sat, 17 Jan 2026 10:29:24 +0100 Message-ID: <23206b5bc44601d0a0bce30adb77cc0f58b49234.1768642102.git.mchehab+huawei@kernel.org> 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 The glibc library limits the return code to 8 bits. We need to stick to this limit when using sys.exit(error_count). Signed-off-by: Mauro Carvalho Chehab Cc: stable@vger.kernel.org --- scripts/kernel-doc.py | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py index 7a1eaf986bcd..1ebb16b9bb08 100755 --- a/scripts/kernel-doc.py +++ b/scripts/kernel-doc.py @@ -116,6 +116,8 @@ SRC_DIR =3D os.path.dirname(os.path.realpath(__file__)) =20 sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) =20 +WERROR_RETURN_CODE =3D 3 + DESC =3D """ Read C language source or header FILEs, extract embedded documentation com= ments, and print formatted documentation to standard output. @@ -176,7 +178,21 @@ class MsgFormatter(logging.Formatter): return logging.Formatter.format(self, record) =20 def main(): - """Main program""" + """ + Main program. + + By default, the return value is: + + - 0: success or Python version is not compatible with + kernel-doc. If -Werror is not used, it will also + return 0 if there are issues at kernel-doc markups; + + - 1: an abnormal condition happened; + + - 2: argparse issued an error; + + - 3: -Werror is used, and one or more unfiltered parse warnings happen= ed. + """ =20 parser =3D argparse.ArgumentParser(formatter_class=3Dargparse.RawTextH= elpFormatter, description=3DDESC) @@ -323,16 +339,12 @@ def main(): =20 if args.werror: print("%s warnings as errors" % error_count) # pylint: disable= =3DC0209 - sys.exit(error_count) + sys.exit(WERROR_RETURN_CODE) =20 if args.verbose: print("%s errors" % error_count) # pylint: disable= =3DC0209 =20 - if args.none: - sys.exit(0) - - sys.exit(error_count) - + sys.exit(0) =20 # Call main method if __name__ =3D=3D "__main__": --=20 2.52.0 From nobody Sun Feb 8 11:43:12 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 19D993328EC; Sat, 17 Jan 2026 09:29:33 +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=1768642173; cv=none; b=uQROCJkiVTG1udalEzMwzy2IVDn3aHLW3Tj1yZP/PBFvoJXoxxBHyOeD219rVGxBzlIT4YrmnbSQQqbizYCy9cLPhkNfx8PsCQKC/nPR8xW/A3d8e5ImL5sSW/rVw77RsJ5RB1gry6LvtDV09cxr2JVt3lND6XAhp7H9Gt4PKO0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768642173; c=relaxed/simple; bh=gIlHO7b2dpX1yT61k9PtOOKZE0nPF7btslse5y1Pu2s=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=iBAkRTQvtTpN2HXjj0jz+8Bq/D037ttdKRr4WRwi/V5VVpoFF9XJWuo5f0cyWm3neTLSvWFCDLcgBt0QDGhvpstiFT35sU6DeTFRGGJ9CvTr8vi5uQiMDBIo7PMleNGO2i3oPLzEN/yDPpAqIhVVYZp4+tvxsnOwCZUH25ast3o= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=BO/lpMzw; 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="BO/lpMzw" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 20914C19423; Sat, 17 Jan 2026 09:29:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768642172; bh=gIlHO7b2dpX1yT61k9PtOOKZE0nPF7btslse5y1Pu2s=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=BO/lpMzw43rE83lYrKTAmtMkYhL5xVLJzHxs3lDTTghR49KXZM8AApGZKCzsgAJGx 0HBU5TYotMfJ5lKs5Xzd8cvd2lS/dh65S2sx99ExtWZi5bpG08/giNCbRWoUaqv3Gb t9MvAw/sqPvz/OpFqdjTXVLMu3qF61moQKN+WgTwtzq3sX1H6sJtgnUnTXdJS5+XHf ePtzmGg/a0y6ia/Q5G3DloKiEUxnkHK8oBhNDUZRzm/PWEETnd6gk98/p2ZsJmiEsW I65RFBGlXfmBrXj+XO5LToWgYxwSvWemB+JqDOD9RyyhR9QWS2stG14G8/UB0pph9e HZBlxyWFZQxvQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vh2cc-00000000fo6-0Vya; Sat, 17 Jan 2026 10:29:30 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Shuah Khan Subject: [PATCH v5 3/4] scripts/kernel-doc: ensure that comments are using our coding style Date: Sat, 17 Jan 2026 10:29:25 +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 Along kernel-doc libs, we opted to have all comments starting/ending with a blank comment line. Use the same style here. Signed-off-by: Mauro Carvalho Chehab --- scripts/kernel-doc.py | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py index 1ebb16b9bb08..f1f3f56edeb5 100755 --- a/scripts/kernel-doc.py +++ b/scripts/kernel-doc.py @@ -3,7 +3,7 @@ # Copyright(c) 2025: Mauro Carvalho Chehab . # # pylint: disable=3DC0103,R0912,R0914,R0915 - +# # NOTE: While kernel-doc requires at least version 3.6 to run, the # command line should work with Python 3.2+ (tested with 3.4). # The rationale is that it shall fail gracefully during Kernel @@ -12,7 +12,7 @@ # - no f-strings can be used on this file. # - the libraries that require newer versions can only be included # after Python version is checked. - +# # Converted from the kernel-doc script originally written in Perl # under GPLv2, copyrighted since 1998 by the following authors: # @@ -197,8 +197,9 @@ def main(): parser =3D argparse.ArgumentParser(formatter_class=3Dargparse.RawTextH= elpFormatter, description=3DDESC) =20 + # # Normal arguments - + # parser.add_argument("-v", "-verbose", "--verbose", action=3D"store_tru= e", help=3D"Verbose output, more warnings and other in= formation.") =20 @@ -213,8 +214,9 @@ def main(): action=3D"store_true", help=3D"Enable line number output (only in ReST mo= de)") =20 + # # Arguments to control the warning behavior - + # parser.add_argument("-Wreturn", "--wreturn", action=3D"store_true", help=3D"Warns about the lack of a return markup on= functions.") =20 @@ -235,8 +237,9 @@ def main(): parser.add_argument("-export-file", "--export-file", action=3D'append', help=3DEXPORT_FILE_DESC) =20 + # # Output format mutually-exclusive group - + # out_group =3D parser.add_argument_group("Output format selection (mutu= ally exclusive)") =20 out_fmt =3D out_group.add_mutually_exclusive_group() @@ -248,8 +251,9 @@ def main(): out_fmt.add_argument("-N", "-none", "--none", action=3D"store_true", help=3D"Do not output documentation, only warning= s.") =20 + # # Output selection mutually-exclusive group - + # sel_group =3D parser.add_argument_group("Output selection (mutually ex= clusive)") sel_mut =3D sel_group.add_mutually_exclusive_group() =20 @@ -262,7 +266,9 @@ def main(): sel_mut.add_argument("-s", "-function", "--symbol", action=3D'append', help=3DFUNCTION_DESC) =20 + # # Those are valid for all 3 types of filter + # parser.add_argument("-n", "-nosymbol", "--nosymbol", action=3D'append', help=3DNOSYMBOL_DESC) =20 @@ -295,9 +301,11 @@ def main(): =20 python_ver =3D sys.version_info[:2] if python_ver < (3,6): + # # Depending on Kernel configuration, kernel-doc --none is called at # build time. As we don't want to break compilation due to the # usage of an old Python version, return 0 here. + # if args.none: logger.error("Python 3.6 or later is required by kernel-doc. s= kipping checks") sys.exit(0) @@ -307,7 +315,9 @@ def main(): if python_ver < (3,7): logger.warning("Python 3.7 or later is required for correct result= s") =20 + # # Import kernel-doc libraries only after checking Python version + # from kdoc.kdoc_files import KernelFiles # pylint: disable= =3DC0415 from kdoc.kdoc_output import RestFormat, ManFormat # pylint: disable= =3DC0415 =20 @@ -346,6 +356,8 @@ def main(): =20 sys.exit(0) =20 +# # Call main method +# if __name__ =3D=3D "__main__": main() --=20 2.52.0 From nobody Sun Feb 8 11:43:12 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 EF6A23321AA; Sat, 17 Jan 2026 09:29:32 +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=1768642173; cv=none; b=NPjWZchizJhYhJObnsK/xqOLL4mnS8Lrc4bM4MgKKmr2PA/9akMCxisXFi1aAJ9W+j2CuHJ4vzbDOpCTXXsuLO3zFSYnych4jmt51T4mEw2hrelmo8I6fyx99ET9H54mz+RXm8HDnVDN3SJ630aVD3YAWCK/PbXzqaLVKV340oA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768642173; c=relaxed/simple; bh=uAgz6NVwdL1fSgq++5Vdt7SvGll1o/f20D2+Kc+Gl6c=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type:Content-Type; b=hbFrGCfRbzR6RqB2nLBAjoSgbsMEgx5ttjsOSYUPTvDxXW0lG2JnrTq0Ndej4FDWpTjKrBH35lS8bHwUAk+oyWHfRk5CWTkB2aI0dFlSiKiBGkkA0tcIrsJLBUGPErAH5TTRAfMtw6FQrGwQegChlZud0Yhx/umJ3LqiAEL5DSU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=sybllAQf; 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="sybllAQf" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 1CAB7C4AF0B; Sat, 17 Jan 2026 09:29:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768642172; bh=uAgz6NVwdL1fSgq++5Vdt7SvGll1o/f20D2+Kc+Gl6c=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=sybllAQfk6XLJ1XUAsuB9WmR9aPN8p7tdcX1PXFujVQ7j3SugGU7HH7XvtbnxCxTy ZDTpgJRHm/5kozVm5TnDdgjg4wxy8ao79v5930/gExoq4nd4+qfeD3NP1Ek/Vv21I7 HgV54NfeLoX5zyyqDz6gfGWFjqwFCm4JAqCiG8CDZmWxxI16YXivyyZrJ8tiVRXIzY 6jGTv/HH0hdN7Lu7KM+Vv8lUdmxYxg9cwh0giv2bbSntX/sWevUM2X/Hi/AFXhJM44 Fu5s83789MkFSkTIv+5jt9VBOiC5LEE/aRmNN2i1KQb7/vsK3meNuKPx8JjFXGDjM0 VGOg7oiXHRBcA== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vh2cc-00000000foA-0dJC; Sat, 17 Jan 2026 10:29:30 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Shuah Khan Subject: [PATCH v5 4/4] scripts/kernel-doc: some fixes to kernel-doc comments Date: Sat, 17 Jan 2026 10:29:26 +0100 Message-ID: <80e96e47af63a46d9a082785bf1bde35f73540d7.1768642102.git.mchehab+huawei@kernel.org> 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-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab There are some typos and English errors in the comments of kernel=E2=80=91d= oc.py. Locate them with the help of an LLM (gpt=E2=80=91oss 14B), executed locally with this prompt: review English grammar and syntax at the comments on the code below: While LLM worked fine for the task of doing an English grammar review for strings, being able to distinguish them from the actual code, it was not is perfect: some things required manual work to fix. - While here, replace: "/**" with: ``/**`` As, if we ever rename this script to kernel_doc.py and add it to Sphinx ext autodoc, we want to avoid this warning: scripts/kernel_doc.py:docstring of kernel_doc:10: WARNING: Inline stron= g start-string without end-string. [docutils] Signed-off-by: Mauro Carvalho Chehab --- scripts/kernel-doc.py | 29 +++++++++++++---------------- 1 file changed, 13 insertions(+), 16 deletions(-) diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py index f1f3f56edeb5..4e3b9cfe3fd7 100755 --- a/scripts/kernel-doc.py +++ b/scripts/kernel-doc.py @@ -9,9 +9,9 @@ # The rationale is that it shall fail gracefully during Kernel # compilation with older Kernel versions. Due to that: # - encoding line is needed here; -# - no f-strings can be used on this file. -# - the libraries that require newer versions can only be included -# after Python version is checked. +# - f-strings cannot be used in this file. +# - libraries that require newer versions can only be included +# after the Python version has been checked. # # Converted from the kernel-doc script originally written in Perl # under GPLv2, copyrighted since 1998 by the following authors: @@ -88,16 +88,13 @@ # Yujie Liu =20 """ -kernel_doc -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -Print formatted kernel documentation to stdout +Print formatted kernel documentation to stdout. =20 Read C language source or header FILEs, extract embedded documentation comments, and print formatted documentation to standard output. =20 -The documentation comments are identified by the "/**" +The documentation comments are identified by the ``/**`` opening comment mark. =20 See Documentation/doc-guide/kernel-doc.rst for the @@ -134,13 +131,13 @@ May be used multiple times. """ =20 EXPORT_DESC =3D """ -Only output documentation for the symbols that have been +Only output documentation for symbols that have been exported using EXPORT_SYMBOL() and related macros in any input FILE or -export-file FILE. """ =20 INTERNAL_DESC =3D """ -Only output documentation for the symbols that have NOT been +Only output documentation for symbols that have NOT been exported using EXPORT_SYMBOL() and related macros in any input FILE or -export-file FILE. """ @@ -163,7 +160,7 @@ Header and C source files to be parsed. """ =20 WARN_CONTENTS_BEFORE_SECTIONS_DESC =3D """ -Warns if there are contents before sections (deprecated). +Warn if there are contents before sections (deprecated). =20 This option is kept just for backward-compatibility, but it does nothing, neither here nor at the original Perl script. @@ -171,7 +168,7 @@ 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""" + """Helper class to format warnings in a similar way to kernel-doc.pl."= "" =20 def format(self, record): record.levelname =3D record.levelname.capitalize() @@ -273,7 +270,7 @@ def main(): help=3DNOSYMBOL_DESC) =20 parser.add_argument("-D", "-no-doc-sections", "--no-doc-sections", - action=3D'store_true', help=3D"Don't outputt DOC s= ections") + action=3D'store_true', help=3D"Don't output DOC se= ctions") =20 parser.add_argument("files", metavar=3D"FILE", nargs=3D"+", help=3DFILES_DESC) @@ -302,12 +299,12 @@ def main(): python_ver =3D sys.version_info[:2] if python_ver < (3,6): # - # Depending on Kernel configuration, kernel-doc --none is called at + # Depending on the Kernel configuration, kernel-doc --none is call= ed at # build time. As we don't want to break compilation due to the # usage of an old Python version, return 0 here. # if args.none: - logger.error("Python 3.6 or later is required by kernel-doc. s= kipping checks") + logger.error("Python 3.6 or later is required by kernel-doc. S= kipping checks") sys.exit(0) =20 sys.exit("Python 3.6 or later is required by kernel-doc. Aborting.= ") @@ -316,7 +313,7 @@ def main(): logger.warning("Python 3.7 or later is required for correct result= s") =20 # - # Import kernel-doc libraries only after checking Python version + # Import kernel-doc libraries only after checking the Python version # from kdoc.kdoc_files import KernelFiles # pylint: disable= =3DC0415 from kdoc.kdoc_output import RestFormat, ManFormat # pylint: disable= =3DC0415 --=20 2.52.0