From nobody Sat Feb 7 17:55:29 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 F09B63191C0; Mon, 19 Jan 2026 12:05:16 +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=1768824317; cv=none; b=Gkgio5OftQnnZD+S+ihbt+c55bAsvlDMh3SmfuV9C1glBl42GDf0GXvaGraSoGJvMw0qlds79WFTg3fjji9izfSZWed+UGwAgyFIlraGlJWixEGQpKEzNuy/djjBrntM1FkDaeGMhkurLi0Ast/+vErEpnu9TGDerVBz/gSAzG8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768824317; c=relaxed/simple; bh=TCIDBeqflVUFZ2smOAiTOF7w3v48ieHVeu+24TcmIW0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=BVFyWDHB3IaIwjTg3yhygkWzxnLYhsWL1x7qEMhUu9nyh1QLIAd7WmlaTqc5qdc3TMvG13BsMHF3Zhx7VcVN8DNVxWO1jDsovB8QgzfOk+KSeukmApQeOnaINr8GeFu7Ins+weJ0BG3Uw5hHE4YifBXWqI9/8rjCF4imBxko/sk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=rrZ4TFb5; 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="rrZ4TFb5" Received: by smtp.kernel.org (Postfix) with ESMTPSA id B40E4C19423; Mon, 19 Jan 2026 12:05:16 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768824316; bh=TCIDBeqflVUFZ2smOAiTOF7w3v48ieHVeu+24TcmIW0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=rrZ4TFb55NBcQyz3r9dSGrbzyc93ALw8HLjSdIbiQiKxwrPzwkbPYYztDh/t1fe6i N6hLzFNJDGsTuCw68zIlJPrHVoPqgB8zSKfTVkhwwIgA/IVZgTlDUZXuJG8XqTjInB M+f4+jo1tAROBOT0wGoZmRjGVrHU+pCrHNazu8koRPZESU6rkp6YoW3uYtRAGV4LKM sZxSWsBykwWQVLGc7x9c/FrtQleMkYPaBAq5bJ23wlpLvjHsMoBGABq9cFj4oLRmVy 61qxK7cXUiJ9WjxJ32QvCZGZGtcSfB5nvQhnp5KIusrKBJB3Ao/IhBNKgJwuSwsC0n 71LKmPEN5K/jQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vho0Q-00000001ZjA-3CpT; Mon, 19 Jan 2026 13:05:14 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , dri-devel@lists.freedesktop.org, intel-gfx@lists.freedesktop.org, linux-kbuild@vger.kernel.org, linux-kernel@vger.kernel.org, workflows@vger.kernel.org, Andy Shevchenko , Mauro Carvalho Chehab , Randy Dunlap , stable@vger.kernel.org Subject: [PATCH 1/9] docs: kdoc: fix logic to handle unissued warnings Date: Mon, 19 Jan 2026 13:04:56 +0100 Message-ID: <95109a6585171da4d6900049deaa2634b41ee743.1768823489.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 Reviewed-by: Mauro Carvalho Chehab --- 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 Sat Feb 7 17:55:29 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 2B2E735970D; Mon, 19 Jan 2026 12:05:17 +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=1768824317; cv=none; b=QZr6I3i2WhiVuW4OW7ndBWPW+ME0KYh652xnYP7kdYo3xVGOLwVm9kn8SsTbFm8IV1Y3CNaHJnuGSrdtc7DLT7qEe2xdZYCiXx1RhLZWzgh1CiUtBFaJ/D0TVsQX2TPF/L9MAesXGh9LyvSH5by0L4MRYm+BkiZDpYq336/m3lY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768824317; c=relaxed/simple; bh=gswQgvIkCvCKkiNyrJA/gedBlbjViDDQyImQR0Lwtf4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=dyFng7SQmvYASmdTWbaThdRnAaA9V7fNezIUnFS+HaSzzqEVy8lg9EcnzVTs6CQGOpNtALKa04sNntTM0iwqavFhuv1aATP7G1fWrE2m+CFil9Ja2YsWbmHmM4mgA+dPbdqGO+QUv1ZEtxe/Fi6sev7pGl+xzFSAhWWIhdZ8Mhw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=RzyRKDQB; 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="RzyRKDQB" Received: by smtp.kernel.org (Postfix) with ESMTPSA id BC637C19424; Mon, 19 Jan 2026 12:05:16 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768824316; bh=gswQgvIkCvCKkiNyrJA/gedBlbjViDDQyImQR0Lwtf4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=RzyRKDQBKZ8Jd5mO530fmCqsSgPVKGTrzQlo0SAFbAu3XO+BVGDp0v53+SCfKNdCt CCpLlB5i4uwnLACxND1kGaKiPd/6DrKPu8UGfBPubqVllKHQxg+e4wrnmpMrW6WXIp BU4Kdnkhjw+Vg1BYLQ5ZAWOGhQDeCjdz2eB+VDrSLYp2q+1yLXbS3YaSDCtREmOQx3 PeqUYx5SKCo+jGk5JoSxWH17jq6ujjtyvvzmssbAiYLhchZNIwdQaPmwOkFutOxae/ 99142H+xXfrRjd+vzmaxQvZSTzk3wR5uNv0YK7s2D3AKZJ75i+0v6Irh3qLVOQ2CWF StaZatb/RdONw== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vho0Q-00000001ZjE-3Jmu; Mon, 19 Jan 2026 13:05:14 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , dri-devel@lists.freedesktop.org, intel-gfx@lists.freedesktop.org, linux-kbuild@vger.kernel.org, linux-kernel@vger.kernel.org, workflows@vger.kernel.org, Mauro Carvalho Chehab , stable@vger.kernel.org Subject: [PATCH 2/9] docs: kdoc: avoid error_count overflows Date: Mon, 19 Jan 2026 13:04:57 +0100 Message-ID: <233d1674db99ed8feb405a2f781de350f0fba0ac.1768823489.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 Reviewed-by: Mauro Carvalho Chehab --- 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 Sat Feb 7 17:55:29 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 F088A1C5D5E; Mon, 19 Jan 2026 12:05:16 +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=1768824317; cv=none; b=KFd0q9CPBfbxKzLOJDU7+N4ZwWoioA5249LEOgL0NKFSkUujLQhUf4wJ9NXG05TORySjUG7fW6ROv/SIaAqMiKlm8j0Rh/P9CzsNawGlrOEB9JS2Dt7AHg6/L6yFj6lB9tiMLdREpEmkX4Hz+KOnMRk8whKI89alFLrRG5aViK0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768824317; c=relaxed/simple; bh=gIlHO7b2dpX1yT61k9PtOOKZE0nPF7btslse5y1Pu2s=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=cyJR9up7juJzJ8qIxgCa7aJbTQHpaTDDZAJzicloYnZ5pz8yb9cbEt0dD1fxo5/sL8+VQNzARZSnEJHT3hfEkhaCIMl3ZlIECJv71tr48jgGktqY23JpHML+pgUF+hGDQAXjwSeBYIq1iEvXl/xtxV+B+Za1rPRgsXhCiywotYk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=cQPLPDTr; 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="cQPLPDTr" Received: by smtp.kernel.org (Postfix) with ESMTPSA id BA878C19425; Mon, 19 Jan 2026 12:05:16 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768824316; bh=gIlHO7b2dpX1yT61k9PtOOKZE0nPF7btslse5y1Pu2s=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=cQPLPDTr9HIYOdHR/wEdulLJPp1fpkTVYYwVsquoQQPDk16XAoVJga5jcBtKxIhhH xtctZVCg8p4w1gGmntAfhG5XFNdd6DmXrpk0el86rDvwRVp+Sy/gjgMPlOOq6tsMlG 7MRy+TppxhgzXmW4Yq0QKTKxqnucEuxHrL7LE79Du4BGlHDnug0AWDQaPUS1F8Ahty UDBXW/dbOYiFSBQ/RB4hMIIZHr/9ZywTNOBuk1mhEKWQ7GU0h8Uta7pu1QvAea5FLJ GvxoK00BLTRZ/L52HxqGhOfmko4ZxWKWOr8Cn4lzck97rWpm+QC0dldNFvTM7ajH6x Azgkup5ORkhNQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vho0Q-00000001ZjI-3Qjw; Mon, 19 Jan 2026 13:05:14 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , dri-devel@lists.freedesktop.org, intel-gfx@lists.freedesktop.org, linux-kbuild@vger.kernel.org, linux-kernel@vger.kernel.org, workflows@vger.kernel.org, Mauro Carvalho Chehab Subject: [PATCH 3/9] docs: kdoc: ensure that comments are using our coding style Date: Mon, 19 Jan 2026 13:04:58 +0100 Message-ID: <50e430acd333a500719205e80ab3b2d297edcd7d.1768823489.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 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 Reviewed-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 Sat Feb 7 17:55:29 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 F0ADF329C6C; Mon, 19 Jan 2026 12:05:16 +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=1768824317; cv=none; b=lJNjv2FRFNV65C2uVTeQWi+NOvY2EaY/Z5xX+R1FXM9t/trKthyBkPCxRPM5+4tEdzJbagPVR/Z3WRybNonZ1BftIkveezV4OU92Oam8+M5dJ5PAZqYkCctQk3AZY0JfsYXiOY3meW/j83cdXPwSeD0aSDAJU5cSIW2pIhfMlIE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768824317; 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=FMvwbkfGHuV1KQXgr4FVMjwtdyarIwKHBPHm7+pr46x1tA41I518KTD9S0ify4V/zEu7QP4ng86uUG+le8EQNIprA1QAFuIHYvxl3g1RENLX8F3trPcWALt+NqRrEkZdIzeXi/vd8PwZv3NQqJKJqUrVBmeulGd8kEqa2YpjElw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=aJ+pWdo0; 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="aJ+pWdo0" Received: by smtp.kernel.org (Postfix) with ESMTPSA id B64FCC4AF09; Mon, 19 Jan 2026 12:05:16 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768824316; bh=uAgz6NVwdL1fSgq++5Vdt7SvGll1o/f20D2+Kc+Gl6c=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=aJ+pWdo0Tq59ur1/vDvnzdzAODQB+0BpPcPaKhE1BlTE+naH79rJGPzNzNg/1DYRO ZUV4usc7G0oiHnnc1nCJ8BmhHcuFIAQi+U5TMFh7g5ea+Xf8vkV9wJoKQK3pamzf2H zRHfcHC0k3jFnAGzcMMtz+gowPOz/+p9rhsVfx6r5mnkcWWTg8x4E6jg+esUdgcWQ8 VTxgxE7AAhpegUBy4MuwntcrXHF/92n4BwbmyFfo60gXGUPlaB35qqPKwb4JZgUuJm UynONt/lasjE6wBmtpgJZawth73DeUtHznc6z4v8o49JqNtDuMDsCanfOxRibMSXAH /Wvx5ONH91W8A== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vho0Q-00000001ZjM-3Xkg; Mon, 19 Jan 2026 13:05:14 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , dri-devel@lists.freedesktop.org, intel-gfx@lists.freedesktop.org, linux-kbuild@vger.kernel.org, linux-kernel@vger.kernel.org, workflows@vger.kernel.org, Mauro Carvalho Chehab Subject: [PATCH 4/9] docs: kdoc: some fixes to kernel-doc comments Date: Mon, 19 Jan 2026 13:04:59 +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-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 Reviewed-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 From nobody Sat Feb 7 17:55:29 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 F0A48320CCD; Mon, 19 Jan 2026 12:05:16 +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=1768824317; cv=none; b=NEq9yWvfoAk2JjgkRm2UH5gJ0d/xfsj6s065m4UG5UGQQF5dMkD4euWVlPVPP1aAWtPaw3c8PWx4hmodSeBRQOYw3bKeIVZDeDG5oAG7wsPYBkbOh0/VZhuxd2by2/2SP/FMT3XyoDAERb1qUBqS4JzZrDXXBwFNJ+e1ohDqHUI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768824317; c=relaxed/simple; bh=y5iZGxGixN2k9HnEvZMtqvRXtngWsH3N6Ec9onhRymc=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=jHnTZIjdVsaZPtSsvAxmL/CH5U/2S9RNn0UXTMTsnp7MFp7d54R2NzOVqyF3DNOuJSQYkhvl7EXCpRZ1UWTNGqjAqPH33iCvY4wwdFCQO1ebVHo+4MI3Ajypm5UZo11F/oSqUHFsch+cdO9D39kWEGSfEtZAqqn9f+QupoFt3vs= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=KoB9JclS; 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="KoB9JclS" Received: by smtp.kernel.org (Postfix) with ESMTPSA id B8407C4AF0C; Mon, 19 Jan 2026 12:05:16 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768824316; bh=y5iZGxGixN2k9HnEvZMtqvRXtngWsH3N6Ec9onhRymc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=KoB9JclSl2SERqOuHQPj5OWv2vJ0D2IgpAiiq76po1yxaLjUg6ccWM88joknbGGrO rkzWB0HdiAIbhFww4fZVwi4fiGze4qT2dfHkbQBB4nDpTcBTJlPwvr+QjL5rSKy+4a oAedl2z6+YasaC8XBDqtHeaMt8mfmebhM60valfqIDTTSm+1xXyQn9GT/Tj1ruNMnl 80+BAU9G3Evl/l5woyEEP2gVGv5CGUdCHiXNS+CvvJHDa5Y6jR9k2PjHDtoHv0p9ro sFAuNwh1GhM9zgg1Y8rVA/35EKKeDcyK9KYSUdd/Lw0PDVURzyvdRpfMUBJa5KPQu1 rH9SM3aIkAi7w== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vho0Q-00000001ZjQ-3epy; Mon, 19 Jan 2026 13:05:14 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , dri-devel@lists.freedesktop.org, intel-gfx@lists.freedesktop.org, linux-kbuild@vger.kernel.org, linux-kernel@vger.kernel.org, workflows@vger.kernel.org, Shuah Khan , Mauro Carvalho Chehab Subject: [PATCH 5/9] docs: kdoc: remove support for an external kernel-doc from sphinx Date: Mon, 19 Jan 2026 13:05:00 +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 From: Jonathan Corbet The ability to build the docs with an external kernel-doc program involves some truly confusing logic and complicates the task of moving kernel-doc out of scripts/. But this feature is not useful for normal documentation builds, and the external kernel-doc can always be run by hand when it needs debugging. So just remove that feature and make life easier. There is still a bunch of logic to build a command line that we never use; the idea is to be able to output it, but I'm not sure if that is worth keeping. Signed-off-by: Jonathan Corbet Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/kerneldoc.py | 53 ++++--------------------------- 1 file changed, 6 insertions(+), 47 deletions(-) diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerne= ldoc.py index d8cdf068ef35..afbab458550a 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -190,35 +190,7 @@ class KernelDocDirective(Directive): =20 return cmd =20 - def run_cmd(self, cmd): - """ - Execute an external kernel-doc command. - """ - - env =3D self.state.document.settings.env - node =3D nodes.section() - - p =3D subprocess.Popen(cmd, stdout=3Dsubprocess.PIPE, stderr=3Dsub= process.PIPE) - out, err =3D p.communicate() - - out, err =3D codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-= 8') - - if p.returncode !=3D 0: - sys.stderr.write(err) - - logger.warning("kernel-doc '%s' failed with return code %d" - % (" ".join(cmd), p.returncode)) - return [nodes.error(None, nodes.paragraph(text =3D "kernel-doc= missing"))] - elif env.config.kerneldoc_verbosity > 0: - sys.stderr.write(err) - - filenames =3D self.parse_args["file_list"] - for filename in filenames: - self.parse_msg(filename, node, out, cmd) - - return node.children - - def parse_msg(self, filename, node, out, cmd): + def parse_msg(self, filename, node, out): """ Handles a kernel-doc output for a given file """ @@ -244,7 +216,7 @@ class KernelDocDirective(Directive): =20 self.do_parse(result, node) =20 - def run_kdoc(self, cmd, kfiles): + def run_kdoc(self, kfiles): """ Execute kernel-doc classes directly instead of running as a separa= te command. @@ -258,23 +230,17 @@ class KernelDocDirective(Directive): filenames =3D self.parse_args["file_list"] =20 for filename, out in kfiles.msg(**self.msg_args, filenames=3Dfilen= ames): - self.parse_msg(filename, node, out, cmd) + self.parse_msg(filename, node, out) =20 return node.children =20 def run(self): - global kfiles - cmd =3D self.handle_args() if self.verbose >=3D 1: logger.info(cmd_str(cmd)) =20 try: - if kfiles: - return self.run_kdoc(cmd, kfiles) - else: - return self.run_cmd(cmd) - + return self.run_kdoc(kfiles) except Exception as e: # pylint: disable=3DW0703 logger.warning("kernel-doc '%s' processing failed with: %s" % (cmd_str(cmd), pformat(e))) @@ -286,15 +252,8 @@ class KernelDocDirective(Directive): =20 def setup_kfiles(app): global kfiles - - kerneldoc_bin =3D app.env.config.kerneldoc_bin - - if kerneldoc_bin and kerneldoc_bin.endswith("kernel-doc.py"): - print("Using Python kernel-doc") - out_style =3D RestFormat() - kfiles =3D KernelFiles(out_style=3Dout_style, logger=3Dlogger) - else: - print(f"Using {kerneldoc_bin}") + out_style =3D RestFormat() + kfiles =3D KernelFiles(out_style=3Dout_style, logger=3Dlogger) =20 =20 def setup(app): --=20 2.52.0 From nobody Sat Feb 7 17:55:29 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 441BB359F84; Mon, 19 Jan 2026 12:05:17 +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=1768824317; cv=none; b=gNZQsPZNZ7bUcaacczTuR5zkH/li7GFQTQoHBMYjfZqphT2WFdv80wX1sam0c7G9OHAH6+XQHRVND6iJKEM5LkppvKE9+LXmWSkjfgrP8sY7kf0WNpQye31Ne1DLQAvGW1O36bExtY3YkfYLDY8VmUbULNUPKcFphQY5dD+83X0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768824317; c=relaxed/simple; bh=2ZahzXGejqZKqYaU9jPgyBkxHVUCgbuE2WJJNrLru4o=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=sEDdSsIHgydwnu9rQNpSb1J8kPiEhlHRH1GC1u036pJius/dj51xkOqx4+/WzIXeJ9zN7C/46990Iz7fmvn2xixpzg4rK9j+VFDBeAahuytyxrGOipcokvUIJs5ZoLCVuXaOx6oI+uHQU0Jfxc2Z6SmDy+BXRiaxc+FAX952zGg= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=KbPtskDD; 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="KbPtskDD" Received: by smtp.kernel.org (Postfix) with ESMTPSA id C0661C2BC87; Mon, 19 Jan 2026 12:05:16 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768824317; bh=2ZahzXGejqZKqYaU9jPgyBkxHVUCgbuE2WJJNrLru4o=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=KbPtskDDj53yIsH9dzAgzFzL0GpcaNljKAEvErrxQZ+WUk0VZvLy6jxV+qwN8Oz7T 0swqNtmiC8stm0NH6CiDYEXOKyfjGzJCJWKoZ+WBsw2M03WptXv63x9WgBhKG/RZDc Avm6pFJCsvrlpUf3Zm4SzDqq0xPNK94sngFLciDH/JGvakL71AseeE7TUXIes6dSvb n092W4ncZ11tzxakktY93DlPVIZ38nTbEuNT4ntqMN24IfMVSkj6/5WyzjR4v4zyAg l8HpcjawBY0z0hFw7rhfEfmYHURzOVaH4o8XXEox919Xnz7CaeE7Feh56Psjeyx2PM BR5EeGK1X8IUw== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vho0Q-00000001ZjV-3nDC; Mon, 19 Jan 2026 13:05:14 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: dri-devel@lists.freedesktop.org, intel-gfx@lists.freedesktop.org, linux-kbuild@vger.kernel.org, linux-kernel@vger.kernel.org, workflows@vger.kernel.org, =?UTF-8?q?Thomas=20Wei=C3=9Fschuh?= , Alex Shi , Avadhut Naik , Carlos Bilbao , Chenguang Zhao , David Airlie , David Disseldorp , Dongliang Mu , Federico Vaga , Gang Yan , Hu Haowen <2023002089@link.tyut.edu.cn>, Jani Nikula , Joonas Lahtinen , Kees Cook , Masahiro Yamada , Mauro Carvalho Chehab , Miguel Ojeda , Nathan Chancellor , Nicolas Schier , Randy Dunlap , Rodrigo Vivi , Shuah Khan , Simona Vetter , Steven Rostedt , Tamir Duberstein , Tvrtko Ursulin , Vincent Mailhol , WangYuli , Yanteng Si , Mauro Carvalho Chehab Subject: [PATCH 6/9] docs: kdoc: move kernel-doc to tools/docs Date: Mon, 19 Jan 2026 13:05:01 +0100 Message-ID: <311d17e403524349940a8b12de6b5e91e554b1f4.1768823489.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 From: Jonathan Corbet kernel-doc is the last documentation-related tool still living outside of the tools/docs directory; the time has come to move it over. [mchehab: fixed kdoc lib location] Signed-off-by: Jonathan Corbet Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Mauro Carvalho Chehab --- Documentation/conf.py | 2 +- Documentation/doc-guide/kernel-doc.rst | 8 ++++---- Documentation/kbuild/kbuild.rst | 2 +- Documentation/process/coding-style.rst | 2 +- .../translations/it_IT/doc-guide/kernel-doc.rst | 8 ++++---- .../translations/sp_SP/process/coding-style.rst | 2 +- .../translations/zh_CN/doc-guide/kernel-doc.rst | 10 +++++----- Documentation/translations/zh_CN/kbuild/kbuild.rst | 2 +- .../translations/zh_CN/process/coding-style.rst | 2 +- .../translations/zh_TW/process/coding-style.rst | 2 +- MAINTAINERS | 2 -- Makefile | 2 +- drivers/gpu/drm/i915/Makefile | 2 +- scripts/kernel-doc | 1 - tools/docs/find-unused-docs.sh | 2 +- scripts/kernel-doc.py =3D> tools/docs/kernel-doc | 2 +- tools/docs/sphinx-build-wrapper | 2 +- 17 files changed, 25 insertions(+), 28 deletions(-) delete mode 120000 scripts/kernel-doc rename scripts/kernel-doc.py =3D> tools/docs/kernel-doc (99%) diff --git a/Documentation/conf.py b/Documentation/conf.py index 1ea2ae5c6276..383d5e5b9d0a 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -582,7 +582,7 @@ pdf_documents =3D [ # kernel-doc extension configuration for running Sphinx directly (e.g. by = Read # the Docs). In a normal build, these are supplied from the Makefile via c= ommand # line arguments. -kerneldoc_bin =3D "../scripts/kernel-doc.py" +kerneldoc_bin =3D "../tools/docs/kernel-doc" # Not used now kerneldoc_srctree =3D ".." =20 def setup(app): diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-gui= de/kernel-doc.rst index b56128d7f5c3..8d2c09fb36e4 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -54,7 +54,7 @@ Running the ``kernel-doc`` tool with increased verbosity = and without actual output generation may be used to verify proper formatting of the documentation comments. For example:: =20 - scripts/kernel-doc -v -none drivers/foo/bar.c + tools/docs/kernel-doc -v -none drivers/foo/bar.c =20 The documentation format of ``.c`` files is also verified by the kernel bu= ild when it is requested to perform extra gcc checks:: @@ -365,7 +365,7 @@ differentiated by whether the macro name is immediately= followed by a left parenthesis ('(') for function-like macros or not followed by one for object-like macros. =20 -Function-like macros are handled like functions by ``scripts/kernel-doc``. +Function-like macros are handled like functions by ``tools/docs/kernel-doc= ``. They may have a parameter list. Object-like macros have do not have a parameter list. =20 @@ -596,8 +596,8 @@ from the source file. =20 The kernel-doc extension is included in the kernel source tree, at ``Documentation/sphinx/kerneldoc.py``. Internally, it uses the -``scripts/kernel-doc`` script to extract the documentation comments from t= he -source. +``tools/docs/kernel-doc`` script to extract the documentation comments from +the source. =20 .. _kernel_doc: =20 diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.= rst index 82826b0332df..5a9013bacfb7 100644 --- a/Documentation/kbuild/kbuild.rst +++ b/Documentation/kbuild/kbuild.rst @@ -180,7 +180,7 @@ architecture. KDOCFLAGS --------- Specify extra (warning/error) flags for kernel-doc checks during the build, -see scripts/kernel-doc for which flags are supported. Note that this doesn= 't +see tools/docs/kernel-doc for which flags are supported. Note that this do= esn't (currently) apply to documentation builds. =20 ARCH diff --git a/Documentation/process/coding-style.rst b/Documentation/process= /coding-style.rst index 258158637f65..35b381230f6e 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -614,7 +614,7 @@ it. =20 When commenting the kernel API functions, please use the kernel-doc format. See the files at :ref:`Documentation/doc-guide/ ` and -``scripts/kernel-doc`` for details. Note that the danger of over-commenting +``tools/docs/kernel-doc`` for details. Note that the danger of over-commen= ting applies to kernel-doc comments all the same. Do not add boilerplate kernel-doc which simply reiterates what's obvious from the signature of the function. diff --git a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst b/Do= cumentation/translations/it_IT/doc-guide/kernel-doc.rst index aa0e31d353d6..bac959b8b7b9 100644 --- a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst +++ b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst @@ -80,7 +80,7 @@ Al fine di verificare che i commenti siano formattati cor= rettamente, potete eseguire il programma ``kernel-doc`` con un livello di verbosit=C3=A0 alto= e senza che questo produca alcuna documentazione. Per esempio:: =20 - scripts/kernel-doc -v -none drivers/foo/bar.c + tools/docs/kernel-doc -v -none drivers/foo/bar.c =20 Il formato della documentazione =C3=A8 verificato della procedura di gener= azione del kernel quando viene richiesto di effettuare dei controlli extra con GC= C:: @@ -378,7 +378,7 @@ distinguono in base al fatto che il nome della macro si= mile a funzione sia immediatamente seguito da una parentesi sinistra ('(') mentre in quelle si= mili a oggetti no. =20 -Le macro simili a funzioni sono gestite come funzioni da ``scripts/kernel-= doc``. +Le macro simili a funzioni sono gestite come funzioni da ``tools/docs/kern= el-doc``. Possono avere un elenco di parametri. Le macro simili a oggetti non hanno = un elenco di parametri. =20 @@ -595,7 +595,7 @@ documentazione presenti nel file sorgente (*source*). =20 L'estensione kernel-doc fa parte dei sorgenti del kernel, la si pu=C3=B2 t= rovare in ``Documentation/sphinx/kerneldoc.py``. Internamente, viene utilizzato -lo script ``scripts/kernel-doc`` per estrarre i commenti di documentazione +lo script ``tools/docs/kernel-doc`` per estrarre i commenti di documentazi= one dai file sorgenti. =20 Come utilizzare kernel-doc per generare pagine man @@ -604,4 +604,4 @@ Come utilizzare kernel-doc per generare pagine man Se volete utilizzare kernel-doc solo per generare delle pagine man, potete farlo direttamente dai sorgenti del kernel:: =20 - $ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^too= ls) | scripts/split-man.pl /tmp/man + $ tools/docs/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^= tools) | scripts/split-man.pl /tmp/man diff --git a/Documentation/translations/sp_SP/process/coding-style.rst b/Do= cumentation/translations/sp_SP/process/coding-style.rst index 025223be9706..7d63aa8426e6 100644 --- a/Documentation/translations/sp_SP/process/coding-style.rst +++ b/Documentation/translations/sp_SP/process/coding-style.rst @@ -633,7 +633,7 @@ posiblemente POR QU=C3=89 hace esto. =20 Al comentar las funciones de la API del kernel, utilice el formato kernel-doc. Consulte los archivos en :ref:`Documentation/doc-guide/ ` -y ``scripts/kernel-doc`` para m=C3=A1s detalles. +y ``tools/docs/kernel-doc`` para m=C3=A1s detalles. =20 El estilo preferido para comentarios largos (de varias l=C3=ADneas) es: =20 diff --git a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst b/Do= cumentation/translations/zh_CN/doc-guide/kernel-doc.rst index ccfb9b8329c2..fb2bbaaa85c1 100644 --- a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst +++ b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst @@ -43,7 +43,7 @@ kernel-doc=E6=B3=A8=E9=87=8A=E7=94=A8 ``/**`` =E4=BD=9C= =E4=B8=BA=E5=BC=80=E5=A7=8B=E6=A0=87=E8=AE=B0=E3=80=82 ``kernel-doc`` =E5= =B7=A5=E5=85=B7=E5=B0=86=E6=8F=90=E5=8F=96 =E7=94=A8=E8=AF=A6=E7=BB=86=E6=A8=A1=E5=BC=8F=E5=92=8C=E4=B8=8D=E7=94=9F= =E6=88=90=E5=AE=9E=E9=99=85=E8=BE=93=E5=87=BA=E6=9D=A5=E8=BF=90=E8=A1=8C ``= kernel-doc`` =E5=B7=A5=E5=85=B7=EF=BC=8C=E5=8F=AF=E4=BB=A5=E9=AA=8C=E8=AF= =81=E6=96=87=E6=A1=A3=E6=B3=A8=E9=87=8A=E7=9A=84=E6=A0=BC=E5=BC=8F =E6=98=AF=E5=90=A6=E6=AD=A3=E7=A1=AE=E3=80=82=E4=BE=8B=E5=A6=82:: =20 - scripts/kernel-doc -v -none drivers/foo/bar.c + tools/docs/kernel-doc -v -none drivers/foo/bar.c =20 =E5=BD=93=E8=AF=B7=E6=B1=82=E6=89=A7=E8=A1=8C=E9=A2=9D=E5=A4=96=E7=9A=84gc= c=E6=A3=80=E6=9F=A5=E6=97=B6=EF=BC=8C=E5=86=85=E6=A0=B8=E6=9E=84=E5=BB=BA= =E5=B0=86=E9=AA=8C=E8=AF=81=E6=96=87=E6=A1=A3=E6=A0=BC=E5=BC=8F:: =20 @@ -473,7 +473,7 @@ doc: *title* =E5=A6=82=E6=9E=9C=E6=B2=A1=E6=9C=89=E9=80=89=E9=A1=B9=EF=BC=8Ckernel-doc= =E6=8C=87=E4=BB=A4=E5=B0=86=E5=8C=85=E5=90=AB=E6=BA=90=E6=96=87=E4=BB=B6=E4= =B8=AD=E7=9A=84=E6=89=80=E6=9C=89=E6=96=87=E6=A1=A3=E6=B3=A8=E9=87=8A=E3=80= =82 =20 kernel-doc=E6=89=A9=E5=B1=95=E5=8C=85=E5=90=AB=E5=9C=A8=E5=86=85=E6=A0=B8= =E6=BA=90=E4=BB=A3=E7=A0=81=E6=A0=91=E4=B8=AD=EF=BC=8C=E4=BD=8D=E4=BA=8E ``= Documentation/sphinx/kerneldoc.py`` =E3=80=82 -=E5=9C=A8=E5=86=85=E9=83=A8=EF=BC=8C=E5=AE=83=E4=BD=BF=E7=94=A8 ``scripts/= kernel-doc`` =E8=84=9A=E6=9C=AC=E4=BB=8E=E6=BA=90=E4=BB=A3=E7=A0=81=E4=B8= =AD=E6=8F=90=E5=8F=96=E6=96=87=E6=A1=A3=E6=B3=A8=E9=87=8A=E3=80=82 +=E5=9C=A8=E5=86=85=E9=83=A8=EF=BC=8C=E5=AE=83=E4=BD=BF=E7=94=A8 ``tools/do= cs/kernel-doc`` =E8=84=9A=E6=9C=AC=E4=BB=8E=E6=BA=90=E4=BB=A3=E7=A0=81=E4= =B8=AD=E6=8F=90=E5=8F=96=E6=96=87=E6=A1=A3=E6=B3=A8=E9=87=8A=E3=80=82 =20 .. _kernel_doc_zh: =20 @@ -482,18 +482,18 @@ kernel-doc=E6=89=A9=E5=B1=95=E5=8C=85=E5=90=AB=E5=9C= =A8=E5=86=85=E6=A0=B8=E6=BA=90=E4=BB=A3=E7=A0=81=E6=A0=91=E4=B8=AD=EF=BC=8C= =E4=BD=8D=E4=BA=8E ``Documentation/sphinx/k =20 =E5=A6=82=E6=9E=9C=E6=82=A8=E5=8F=AA=E6=83=B3=E4=BD=BF=E7=94=A8kernel-doc= =E7=94=9F=E6=88=90=E6=89=8B=E5=86=8C=E9=A1=B5=EF=BC=8C=E5=8F=AF=E4=BB=A5=E4= =BB=8E=E5=86=85=E6=A0=B8git=E6=A0=91=E8=BF=99=E6=A0=B7=E5=81=9A:: =20 - $ scripts/kernel-doc -man \ + $ tools/docs/kernel-doc -man \ $(git grep -l '/\*\*' -- :^Documentation :^tools) \ | scripts/split-man.pl /tmp/man =20 =E4=B8=80=E4=BA=9B=E6=97=A7=E7=89=88=E6=9C=AC=E7=9A=84git=E4=B8=8D=E6=94= =AF=E6=8C=81=E8=B7=AF=E5=BE=84=E6=8E=92=E9=99=A4=E8=AF=AD=E6=B3=95=E7=9A=84= =E6=9F=90=E4=BA=9B=E5=8F=98=E4=BD=93=E3=80=82 =E4=BB=A5=E4=B8=8B=E5=91=BD=E4=BB=A4=E4=B9=8B=E4=B8=80=E5=8F=AF=E8=83=BD= =E9=80=82=E7=94=A8=E4=BA=8E=E8=BF=99=E4=BA=9B=E7=89=88=E6=9C=AC:: =20 - $ scripts/kernel-doc -man \ + $ tools/docs/kernel-doc -man \ $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \ | scripts/split-man.pl /tmp/man =20 - $ scripts/kernel-doc -man \ + $ tools/docs/kernel-doc -man \ $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools"= ) \ | scripts/split-man.pl /tmp/man =20 diff --git a/Documentation/translations/zh_CN/kbuild/kbuild.rst b/Documenta= tion/translations/zh_CN/kbuild/kbuild.rst index 57f5cf5b2cdd..a477b4b08958 100644 --- a/Documentation/translations/zh_CN/kbuild/kbuild.rst +++ b/Documentation/translations/zh_CN/kbuild/kbuild.rst @@ -174,7 +174,7 @@ UTS_MACHINE =E5=8F=98=E9=87=8F=EF=BC=88=E5=9C=A8=E6=9F= =90=E4=BA=9B=E6=9E=B6=E6=9E=84=E4=B8=AD=E8=BF=98=E5=8C=85=E6=8B=AC=E5=86=85= =E6=A0=B8=E9=85=8D=E7=BD=AE=EF=BC=89=E6=9D=A5=E7=8C=9C=E6=B5=8B=E6=AD=A3=E7= =A1=AE KDOCFLAGS --------- =E6=8C=87=E5=AE=9A=E5=9C=A8=E6=9E=84=E5=BB=BA=E8=BF=87=E7=A8=8B=E4=B8=AD= =E7=94=A8=E4=BA=8E kernel-doc =E6=A3=80=E6=9F=A5=E7=9A=84=E9=A2=9D=E5=A4=96= =EF=BC=88=E8=AD=A6=E5=91=8A/=E9=94=99=E8=AF=AF=EF=BC=89=E6=A0=87=E5=BF=97= =EF=BC=8C=E6=9F=A5=E7=9C=8B -scripts/kernel-doc =E4=BA=86=E8=A7=A3=E6=94=AF=E6=8C=81=E7=9A=84=E6=A0=87= =E5=BF=97=E3=80=82=E8=AF=B7=E6=B3=A8=E6=84=8F=EF=BC=8C=E8=BF=99=E7=9B=AE=E5= =89=8D=E4=B8=8D=E9=80=82=E7=94=A8=E4=BA=8E=E6=96=87=E6=A1=A3=E6=9E=84=E5=BB= =BA=E3=80=82 +tools/docs/kernel-doc =E4=BA=86=E8=A7=A3=E6=94=AF=E6=8C=81=E7=9A=84=E6=A0= =87=E5=BF=97=E3=80=82=E8=AF=B7=E6=B3=A8=E6=84=8F=EF=BC=8C=E8=BF=99=E7=9B=AE= =E5=89=8D=E4=B8=8D=E9=80=82=E7=94=A8=E4=BA=8E=E6=96=87=E6=A1=A3=E6=9E=84=E5= =BB=BA=E3=80=82 =20 ARCH ---- diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Do= cumentation/translations/zh_CN/process/coding-style.rst index 0484d0c65c25..5a342a024c01 100644 --- a/Documentation/translations/zh_CN/process/coding-style.rst +++ b/Documentation/translations/zh_CN/process/coding-style.rst @@ -545,7 +545,7 @@ Linux =E9=87=8C=E8=BF=99=E6=98=AF=E6=8F=90=E5=80=A1=E7= =9A=84=E5=81=9A=E6=B3=95=EF=BC=8C=E5=9B=A0=E4=B8=BA=E8=BF=99=E6=A0=B7=E5=8F= =AF=E4=BB=A5=E5=BE=88=E7=AE=80=E5=8D=95=E7=9A=84=E7=BB=99=E8=AF=BB=E8=80=85= =E6=8F=90=E4=BE=9B =E4=B9=9F=E5=8F=AF=E4=BB=A5=E5=8A=A0=E4=B8=8A=E5=AE=83=E5=81=9A=E8=BF=99= =E4=BA=9B=E4=BA=8B=E6=83=85=E7=9A=84=E5=8E=9F=E5=9B=A0=E3=80=82 =20 =E5=BD=93=E6=B3=A8=E9=87=8A=E5=86=85=E6=A0=B8 API =E5=87=BD=E6=95=B0=E6=97= =B6=EF=BC=8C=E8=AF=B7=E4=BD=BF=E7=94=A8 kernel-doc =E6=A0=BC=E5=BC=8F=E3=80= =82=E8=AF=A6=E8=A7=81 -Documentation/translations/zh_CN/doc-guide/index.rst =E5=92=8C scripts/ker= nel-doc =E3=80=82 +Documentation/translations/zh_CN/doc-guide/index.rst =E5=92=8C tools/docs/= kernel-doc =E3=80=82 =20 =E9=95=BF (=E5=A4=9A=E8=A1=8C) =E6=B3=A8=E9=87=8A=E7=9A=84=E9=A6=96=E9=80= =89=E9=A3=8E=E6=A0=BC=E6=98=AF=EF=BC=9A =20 diff --git a/Documentation/translations/zh_TW/process/coding-style.rst b/Do= cumentation/translations/zh_TW/process/coding-style.rst index 311c6f6bad0b..e2ba97b3d8bb 100644 --- a/Documentation/translations/zh_TW/process/coding-style.rst +++ b/Documentation/translations/zh_TW/process/coding-style.rst @@ -548,7 +548,7 @@ Linux =E8=A3=8F=E9=80=99=E6=98=AF=E6=8F=90=E5=80=A1=E7= =9A=84=E5=81=9A=E6=B3=95=EF=BC=8C=E5=9B=A0=E7=88=B2=E9=80=99=E6=A8=A3=E5=8F= =AF=E4=BB=A5=E5=BE=88=E7=B0=A1=E5=96=AE=E7=9A=84=E7=B5=A6=E8=AE=80=E8=80=85= =E6=8F=90=E4=BE=9B =E4=B9=9F=E5=8F=AF=E4=BB=A5=E5=8A=A0=E4=B8=8A=E5=AE=83=E5=81=9A=E9=80=99= =E4=BA=9B=E4=BA=8B=E6=83=85=E7=9A=84=E5=8E=9F=E5=9B=A0=E3=80=82 =20 =E7=95=B6=E8=A8=BB=E9=87=8B=E5=85=A7=E6=A0=B8 API =E5=87=BD=E6=95=B8=E6=99= =82=EF=BC=8C=E8=AB=8B=E4=BD=BF=E7=94=A8 kernel-doc =E6=A0=BC=E5=BC=8F=E3=80= =82=E8=A9=B3=E8=A6=8B -Documentation/translations/zh_CN/doc-guide/index.rst =E5=92=8C scripts/ker= nel-doc =E3=80=82 +Documentation/translations/zh_CN/doc-guide/index.rst =E5=92=8C tools/docs/= kernel-doc =E3=80=82 =20 =E9=95=B7 (=E5=A4=9A=E8=A1=8C) =E8=A8=BB=E9=87=8B=E7=9A=84=E9=A6=96=E9=81= =B8=E9=A2=A8=E6=A0=BC=E6=98=AF=EF=BC=9A =20 diff --git a/MAINTAINERS b/MAINTAINERS index 02ec226dd571..d009e2da2215 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -7523,7 +7523,6 @@ S: Maintained P: Documentation/doc-guide/maintainer-profile.rst T: git git://git.lwn.net/linux.git docs-next F: Documentation/ -F: scripts/kernel-doc* F: tools/lib/python/* F: tools/docs/ F: tools/net/ynl/pyynl/lib/doc_generator.py @@ -7561,7 +7560,6 @@ M: Mauro Carvalho Chehab L: linux-doc@vger.kernel.org S: Maintained F: Documentation/sphinx/ -F: scripts/kernel-doc* F: tools/lib/python/* F: tools/docs/ =20 diff --git a/Makefile b/Makefile index 3cd00b62cde9..81a4ab11256c 100644 --- a/Makefile +++ b/Makefile @@ -460,7 +460,7 @@ HOSTPKG_CONFIG =3D pkg-config =20 # the KERNELDOC macro needs to be exported, as scripts/Makefile.build # has a logic to call it -KERNELDOC =3D $(srctree)/scripts/kernel-doc.py +KERNELDOC =3D $(srctree)/tools/docs/kernel-doc export KERNELDOC =20 KBUILD_USERHOSTCFLAGS :=3D -Wall -Wmissing-prototypes -Wstrict-prototypes \ diff --git a/drivers/gpu/drm/i915/Makefile b/drivers/gpu/drm/i915/Makefile index 4db24050edb0..c979c579de66 100644 --- a/drivers/gpu/drm/i915/Makefile +++ b/drivers/gpu/drm/i915/Makefile @@ -443,7 +443,7 @@ always-$(CONFIG_DRM_I915_WERROR) +=3D \ =20 quiet_cmd_hdrtest =3D HDRTEST $(patsubst %.hdrtest,%.h,$@) cmd_hdrtest =3D $(CC) $(filter-out $(CFLAGS_GCOV), $(c_flags)) -S -o= /dev/null -x c /dev/null -include $<; \ - $(srctree)/scripts/kernel-doc -none -Werror $<; touch $@ + $(KERNELDOC) -none -Werror $<; touch $@ =20 $(obj)/%.hdrtest: $(src)/%.h FORCE $(call if_changed_dep,hdrtest) diff --git a/scripts/kernel-doc b/scripts/kernel-doc deleted file mode 120000 index 3b6ef807791a..000000000000 --- a/scripts/kernel-doc +++ /dev/null @@ -1 +0,0 @@ -kernel-doc.py \ No newline at end of file diff --git a/tools/docs/find-unused-docs.sh b/tools/docs/find-unused-docs.sh index ca4e607ec3f7..53514c759dc1 100755 --- a/tools/docs/find-unused-docs.sh +++ b/tools/docs/find-unused-docs.sh @@ -54,7 +54,7 @@ for file in `find $1 -name '*.c'`; do if [[ ${FILES_INCLUDED[$file]+_} ]]; then continue; fi - str=3D$(PYTHONDONTWRITEBYTECODE=3D1 scripts/kernel-doc -export "$file" 2>= /dev/null) + str=3D$(PYTHONDONTWRITEBYTECODE=3D1 tools/docs/kernel-doc -export "$file"= 2>/dev/null) if [[ -n "$str" ]]; then echo "$file" fi diff --git a/scripts/kernel-doc.py b/tools/docs/kernel-doc similarity index 99% rename from scripts/kernel-doc.py rename to tools/docs/kernel-doc index 4e3b9cfe3fd7..a19a92566780 100755 --- a/scripts/kernel-doc.py +++ b/tools/docs/kernel-doc @@ -108,7 +108,7 @@ import sys =20 # Import Python modules =20 -LIB_DIR =3D "../tools/lib/python" +LIB_DIR =3D "../lib/python" SRC_DIR =3D os.path.dirname(os.path.realpath(__file__)) =20 sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrap= per index 7a5fcef25429..cb2a5005e633 100755 --- a/tools/docs/sphinx-build-wrapper +++ b/tools/docs/sphinx-build-wrapper @@ -246,7 +246,7 @@ class SphinxBuilder: # self.sphinxbuild =3D os.environ.get("SPHINXBUILD", "sphinx-build") self.kerneldoc =3D self.get_path(os.environ.get("KERNELDOC", - "scripts/kernel-doc.= py")) + "tools/docs/kernel-d= oc")) self.builddir =3D self.get_path(builddir, use_cwd=3DTrue, abs_path= =3DTrue) =20 # --=20 2.52.0 From nobody Sat Feb 7 17:55:29 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 2B5EB359712; Mon, 19 Jan 2026 12:05:17 +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=1768824317; cv=none; b=es6deBDpEGVKJakFL2L1Hk9O03xeTR/wjSLbaupYNX9scJl+vclWD53Y+bXYLcEE+PeriGqojxG/jUieldSOuo7ATBsXptOV5EPVXZi04AadHrp9JSAyxSKR9MdLKaFGmhEBdt8FpziJvGsuZhUMVlE/ONXjUMjtP88QSEidVVM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768824317; c=relaxed/simple; bh=kGt9gNhMuRj9+jM9PcGfmUvM8H3qve1/pTvOonlpy+g=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=DFU50qQ8fxq1RWwReUws71BEURVyjZZML3qrQMO60cHL2ASRzqwVOhzWHetSvvuLz2gO8sr1GEkgKhlCzKy+MXJJMmdtU3rUBa6+tABrJydeACM4hhlPzEzJtSYl3m32VH1WysyPZqptLmUNR/p4qX6VmMDnxDGDywtZfLGBrnA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=pU0+yURc; 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="pU0+yURc" Received: by smtp.kernel.org (Postfix) with ESMTPSA id C2953C2BCAF; Mon, 19 Jan 2026 12:05:16 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768824316; bh=kGt9gNhMuRj9+jM9PcGfmUvM8H3qve1/pTvOonlpy+g=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=pU0+yURc1Q45u8r1PvFHHPODmTRWMuC9YrkASEB967Elx3REu6QhasyY+7FBLquMj SGUO+N+BnEdM7QH4q7SzrZuijRYoPNaX3zw5p56FJQ2ylQXCTLJKvfHpm+zYSZu7gG /hpSC9wYb6vV6NfQ02yuPdVFxTKrFGqVqLMpnuXqODZA5xGm0u0GVVEzE08kdmPh8L 6/ar92+aciGUNsWmT1d+qnov7ZCrkkbc8bdgC2pHe2Wq7pmGLfDJVCKm41jGZNzPEm iu60r+QYUlbLB34qzOZ5BJ6HIhw4s1HckZur1X8zUVZrrVXLR5/IGY/XiqXpM6xzIY I1F4kXhuFzG6Q== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vho0Q-00000001ZjY-3uFL; Mon, 19 Jan 2026 13:05:14 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , dri-devel@lists.freedesktop.org, intel-gfx@lists.freedesktop.org, linux-kbuild@vger.kernel.org, linux-kernel@vger.kernel.org, workflows@vger.kernel.org, Mauro Carvalho Chehab , Shuah Khan Subject: [PATCH 7/9] docs: kdoc: move the return values to the helper message Date: Mon, 19 Jan 2026 13:05:02 +0100 Message-ID: <3bcfa48016770929fcd073376515e3ff0b777ea8.1768823489.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 It makes sense to describe what kernel-doc is expected to return on its help message. Move such messages to argparse epilog. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Mauro Carvalho Chehab --- tools/docs/kernel-doc | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/tools/docs/kernel-doc b/tools/docs/kernel-doc index a19a92566780..902397804e80 100755 --- a/tools/docs/kernel-doc +++ b/tools/docs/kernel-doc @@ -166,6 +166,20 @@ This option is kept just for backward-compatibility, b= ut it does nothing, neither here nor at the original Perl script. """ =20 +EPILOG =3D """ +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: When -Werror is used, it means that one or more unfiltered parse + warnings happened. +""" =20 class MsgFormatter(logging.Formatter): """Helper class to format warnings in a similar way to kernel-doc.pl."= "" @@ -178,21 +192,10 @@ def main(): """ Main program. =20 - 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) + description=3DDESC, epilog=3DEPILOG) =20 # # Normal arguments --=20 2.52.0 From nobody Sat Feb 7 17:55:29 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 2824B22CBF1; Mon, 19 Jan 2026 12:05:17 +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=1768824317; cv=none; b=coiayLhncQJ7AM0cS83hHgzf/zleYcCCJyatAz74Ho7rx0blfI04KUuliOkHqU44pGgTOB/9gJ2z0BMWRDd987EGiMFtSFjkP9cnQi/S919knKg0xrHrhQdoGbKN3aud3Mdhb5rlAGsLUvGJCM9tgBUHFHyMK6CNWUcp/2y/aNU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768824317; c=relaxed/simple; bh=EvzMyaM5H9x2cdY7aG4hx2yahivm2IErGiiDZ+0Gw88=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=sInetzQ4mpbPHYRGxjZXGXgM3nFwJS+nWmx7cKGFUvYvVU1NJlU/r6l6bSHM2zxOHp0GFfNa7MCQvz+WilVvWFOPwRtfTAwYd+v9WmqPvaJfy8Qd7rpNfpaSD+7GYMR+D+BqW9DwBiKW6UOMhh64pQp1cf4ykL56PTRBWsYA1dA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=hCTpfTKx; 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="hCTpfTKx" Received: by smtp.kernel.org (Postfix) with ESMTPSA id BE43EC2BC86; Mon, 19 Jan 2026 12:05:16 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768824316; bh=EvzMyaM5H9x2cdY7aG4hx2yahivm2IErGiiDZ+0Gw88=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=hCTpfTKxH0DGzVRPmdKdiK5e/RfGOYHTECK5WOOWL7r9JIR7CEADDA+mTwhjfo2p2 pkMaHVsA9T1mBYb0zjSsgr7OEn3ZLUn++4ro1UfgJxPEgRz1LEV4enYmrU+MmWkb7a FN7oVaNa45pBk4dOpJ/v/7SxVX6ujn+7ZjhmXM+/Vhl2AI9eQdNNPZInJODieYedYq rmnleEskBEZ6EyG5EGb0Og7vOvSDI1LQQH++QXKMNTL1yEqDzcImoeFPGQP3iuaHu8 2xGBctAFKc0tRFdCoaQ4KImKPoERLLr2uyPQdyqJOFKPlHur/ot9rXTpizNyGbqyBb K7EKm8trcFpug== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vho0Q-00000001Zjd-41eG; Mon, 19 Jan 2026 13:05:14 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , dri-devel@lists.freedesktop.org, intel-gfx@lists.freedesktop.org, linux-kbuild@vger.kernel.org, linux-kernel@vger.kernel.org, workflows@vger.kernel.org, Shuah Khan Subject: [PATCH 8/9] docs: kdoc: improve description of MsgFormatter Date: Mon, 19 Jan 2026 13:05:03 +0100 Message-ID: <94269990e2d665bec08a1b6f4d28d84939cb9d83.1768823489.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 description there is quite vague. Make it clearer. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Mauro Carvalho Chehab --- tools/docs/kernel-doc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/tools/docs/kernel-doc b/tools/docs/kernel-doc index 902397804e80..aed09f9a54dd 100755 --- a/tools/docs/kernel-doc +++ b/tools/docs/kernel-doc @@ -182,7 +182,10 @@ return 0 if there are issues at kernel-doc markups; """ =20 class MsgFormatter(logging.Formatter): - """Helper class to format warnings in a similar way to kernel-doc.pl."= "" + """ + Helper class to capitalize errors and warnings, the same way + the venerable (now retired) kernel-doc.pl used to do. + """ =20 def format(self, record): record.levelname =3D record.levelname.capitalize() --=20 2.52.0 From nobody Sat Feb 7 17:55:29 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 2B1E93596F9; Mon, 19 Jan 2026 12:05:17 +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=1768824317; cv=none; b=Qehp/dWomLy522eFHpFJGLz3YEawfjRt/3PmrmMF+CSJN99evaQqXwWAL5TFoDAajVDIM9y8cud6cXVhdLt82FSQfRhcohq8nnLjSywMq+gT1ZGAWZgeQNkM3S+OfpW8fI5CgLQqhs6H7zNQB8+YSCsmsygCc5ViJbIn14VyyGY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768824317; c=relaxed/simple; bh=6HyC5gF4ScinHY1gGeYNGGYvsoRZQIoC1BWSJQdTkY4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=Lb6cwegxGrTTUKPQJUJjwMVcFGi1K/nJFVu5D/EmTURwql0q/M20voBKV1Ez331+rjiiKrF16KTwv0SRpgfXhGNCz5ppCs2cb7Ki4vTLGEleUwPstNN0iUFMHpUursofrQRvaYkxcUwXvH9IYnGs96GK1kqtd0iZMUS7Tld4bP8= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=WvOuF7hD; 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="WvOuF7hD" Received: by smtp.kernel.org (Postfix) with ESMTPSA id C4FDFC2BC9E; Mon, 19 Jan 2026 12:05:16 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1768824316; bh=6HyC5gF4ScinHY1gGeYNGGYvsoRZQIoC1BWSJQdTkY4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=WvOuF7hDdCBaQHihY9OW2YC1MzFJB74MOokdSvhwGI85VRZ6Ev5ixzSbIBVoGZb0/ AmbHlcUNZ2uPeFv1VnM9Qa7+zTcxklTBwakBGzeGuORRTwf/v0c317Hhqo3pHRQvA8 xN0ekp0C1rZw+mLt2vegSQ6so20BWtxxGtdy+loRJ5Q8MNLVrGGWAYazLjJon10GlF g9EbikW4yrmdSyIR3ntYNzXo9x6GcoTddi06ePHkoshuq6hlkf1qMgLFNTit1g9/Rc 7z/wVoOni+N0u5k5pdd+YSlwDfNSmUkHEuPrq6WVsUrAwa34hFYy2oxu1hnL2sshDG vxQE1+IuvzqjQ== Received: from mchehab by mail.kernel.org with local (Exim 4.99) (envelope-from ) id 1vho0Q-00000001Zjj-48cY; Mon, 19 Jan 2026 13:05:14 +0100 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , dri-devel@lists.freedesktop.org, intel-gfx@lists.freedesktop.org, linux-kbuild@vger.kernel.org, linux-kernel@vger.kernel.org, workflows@vger.kernel.org, Mauro Carvalho Chehab , Shuah Khan Subject: [PATCH 9/9] docs: conf.py: get rid of the now unused kerneldoc_bin env var Date: Mon, 19 Jan 2026 13:05:04 +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 In the past, this contained the location of the binary file to parse kernel-doc. Nowadays, it is used only for debugging purposes, inside kerneldoc.py extension. Move it to sphinx/kerneldoc.py, to avoid needing to handle with it on several places. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Mauro Carvalho Chehab --- Documentation/conf.py | 4 ---- Documentation/sphinx/kerneldoc.py | 7 +++++-- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 383d5e5b9d0a..65df81a9e414 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -579,10 +579,6 @@ pdf_documents =3D [ ("kernel-documentation", "Kernel", "Kernel", "J. Random Bozo"), ] =20 -# kernel-doc extension configuration for running Sphinx directly (e.g. by = Read -# the Docs). In a normal build, these are supplied from the Makefile via c= ommand -# line arguments. -kerneldoc_bin =3D "../tools/docs/kernel-doc" # Not used now kerneldoc_srctree =3D ".." =20 def setup(app): diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerne= ldoc.py index afbab458550a..c1cadb4eb099 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -47,6 +47,10 @@ sys.path.insert(0, os.path.join(srctree, "tools/lib/pyth= on")) from kdoc.kdoc_files import KernelFiles from kdoc.kdoc_output import RestFormat =20 +# Used when verbose is active to show how to reproduce kernel-doc +# issues via command line +kerneldoc_bin =3D "tools/docs/kernel-doc" + __version__ =3D '1.0' kfiles =3D None logger =3D logging.getLogger(__name__) @@ -95,7 +99,7 @@ class KernelDocDirective(Directive): def handle_args(self): =20 env =3D self.state.document.settings.env - cmd =3D [env.config.kerneldoc_bin, '-rst', '-enable-lineno'] + cmd =3D [kerneldoc_bin, '-rst', '-enable-lineno'] =20 filename =3D env.config.kerneldoc_srctree + '/' + self.arguments[0] =20 @@ -257,7 +261,6 @@ def setup_kfiles(app): =20 =20 def setup(app): - app.add_config_value('kerneldoc_bin', None, 'env') app.add_config_value('kerneldoc_srctree', None, 'env') app.add_config_value('kerneldoc_verbosity', 1, 'env') =20 --=20 2.52.0