From 802774d8539fa73487190ec45438777a3c38d424 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Jan 2026 13:04:57 +0100 Subject: docs: kdoc: avoid error_count overflows 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 Signed-off-by: Jonathan Corbet Message-ID: <233d1674db99ed8feb405a2f781de350f0fba0ac.1768823489.git.mchehab+huawei@kernel.org> --- scripts/kernel-doc.py | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) (limited to 'scripts/kernel-doc.py') 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 = os.path.dirname(os.path.realpath(__file__)) sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) +WERROR_RETURN_CODE = 3 + DESC = """ Read C language source or header FILEs, extract embedded documentation comments, and print formatted documentation to standard output. @@ -176,7 +178,21 @@ class MsgFormatter(logging.Formatter): return logging.Formatter.format(self, record) 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 happened. + """ parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter, description=DESC) @@ -323,16 +339,12 @@ def main(): if args.werror: print("%s warnings as errors" % error_count) # pylint: disable=C0209 - sys.exit(error_count) + sys.exit(WERROR_RETURN_CODE) if args.verbose: print("%s errors" % error_count) # pylint: disable=C0209 - if args.none: - sys.exit(0) - - sys.exit(error_count) - + sys.exit(0) # Call main method if __name__ == "__main__": -- cgit v1.2.3 From bd28e99720f3f070e80551b5e94695640d3a730a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Jan 2026 13:04:58 +0100 Subject: docs: kdoc: ensure that comments are using our coding style 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 Signed-off-by: Jonathan Corbet Message-ID: <50e430acd333a500719205e80ab3b2d297edcd7d.1768823489.git.mchehab+huawei@kernel.org> --- scripts/kernel-doc.py | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) (limited to 'scripts/kernel-doc.py') 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=C0103,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 = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter, description=DESC) + # # Normal arguments - + # parser.add_argument("-v", "-verbose", "--verbose", action="store_true", help="Verbose output, more warnings and other information.") @@ -213,8 +214,9 @@ def main(): action="store_true", help="Enable line number output (only in ReST mode)") + # # Arguments to control the warning behavior - + # parser.add_argument("-Wreturn", "--wreturn", action="store_true", help="Warns about the lack of a return markup on functions.") @@ -235,8 +237,9 @@ def main(): parser.add_argument("-export-file", "--export-file", action='append', help=EXPORT_FILE_DESC) + # # Output format mutually-exclusive group - + # out_group = parser.add_argument_group("Output format selection (mutually exclusive)") out_fmt = out_group.add_mutually_exclusive_group() @@ -248,8 +251,9 @@ def main(): out_fmt.add_argument("-N", "-none", "--none", action="store_true", help="Do not output documentation, only warnings.") + # # Output selection mutually-exclusive group - + # sel_group = parser.add_argument_group("Output selection (mutually exclusive)") sel_mut = sel_group.add_mutually_exclusive_group() @@ -262,7 +266,9 @@ def main(): sel_mut.add_argument("-s", "-function", "--symbol", action='append', help=FUNCTION_DESC) + # # Those are valid for all 3 types of filter + # parser.add_argument("-n", "-nosymbol", "--nosymbol", action='append', help=NOSYMBOL_DESC) @@ -295,9 +301,11 @@ def main(): python_ver = 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. skipping 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 results") + # # Import kernel-doc libraries only after checking Python version + # from kdoc.kdoc_files import KernelFiles # pylint: disable=C0415 from kdoc.kdoc_output import RestFormat, ManFormat # pylint: disable=C0415 @@ -346,6 +356,8 @@ def main(): sys.exit(0) +# # Call main method +# if __name__ == "__main__": main() -- cgit v1.2.3 From 6cc45ee5df3bd89c8fa62aa2be91f747938686a1 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Jan 2026 13:04:59 +0100 Subject: docs: kdoc: some fixes to kernel-doc comments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit There are some typos and English errors in the comments of kernel‑doc.py. Locate them with the help of an LLM (gpt‑oss 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 strong start-string without end-string. [docutils] Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID: --- scripts/kernel-doc.py | 29 +++++++++++++---------------- 1 file changed, 13 insertions(+), 16 deletions(-) (limited to 'scripts/kernel-doc.py') 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 """ -kernel_doc -========== - -Print formatted kernel documentation to stdout +Print formatted kernel documentation to stdout. Read C language source or header FILEs, extract embedded documentation comments, and print formatted documentation to standard output. -The documentation comments are identified by the "/**" +The documentation comments are identified by the ``/**`` opening comment mark. See Documentation/doc-guide/kernel-doc.rst for the @@ -134,13 +131,13 @@ May be used multiple times. """ EXPORT_DESC = """ -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. """ INTERNAL_DESC = """ -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. """ WARN_CONTENTS_BEFORE_SECTIONS_DESC = """ -Warns if there are contents before sections (deprecated). +Warn if there are contents before sections (deprecated). 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. 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.""" def format(self, record): record.levelname = record.levelname.capitalize() @@ -273,7 +270,7 @@ def main(): help=NOSYMBOL_DESC) parser.add_argument("-D", "-no-doc-sections", "--no-doc-sections", - action='store_true', help="Don't outputt DOC sections") + action='store_true', help="Don't output DOC sections") parser.add_argument("files", metavar="FILE", nargs="+", help=FILES_DESC) @@ -302,12 +299,12 @@ def main(): python_ver = 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 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. skipping checks") + logger.error("Python 3.6 or later is required by kernel-doc. Skipping checks") sys.exit(0) 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 results") # - # 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=C0415 from kdoc.kdoc_output import RestFormat, ManFormat # pylint: disable=C0415 -- cgit v1.2.3 From eba6ffd126cd52358181ed5a179644a161f9c65f Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 19 Jan 2026 13:05:01 +0100 Subject: docs: kdoc: move kernel-doc to tools/docs 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: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID: <311d17e403524349940a8b12de6b5e91e554b1f4.1768823489.git.mchehab+huawei@kernel.org> --- 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 - scripts/kernel-doc.py | 360 --------------------- tools/docs/find-unused-docs.sh | 2 +- tools/docs/kernel-doc | 360 +++++++++++++++++++++ tools/docs/sphinx-build-wrapper | 2 +- 18 files changed, 384 insertions(+), 387 deletions(-) delete mode 120000 scripts/kernel-doc delete mode 100755 scripts/kernel-doc.py create mode 100755 tools/docs/kernel-doc (limited to 'scripts/kernel-doc.py') diff --git a/Documentation/conf.py b/Documentation/conf.py index 16d025af1f30..652be9221246 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -585,7 +585,7 @@ pdf_documents = [ # 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 command # line arguments. -kerneldoc_bin = "../scripts/kernel-doc.py" +kerneldoc_bin = "../tools/docs/kernel-doc" # Not used now kerneldoc_srctree = ".." def setup(app): diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/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:: - scripts/kernel-doc -v -none drivers/foo/bar.c + tools/docs/kernel-doc -v -none drivers/foo/bar.c The documentation format of ``.c`` files is also verified by the kernel build 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. -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. @@ -596,8 +596,8 @@ from the source file. 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 the -source. +``tools/docs/kernel-doc`` script to extract the documentation comments from +the source. .. _kernel_doc: 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 doesn't (currently) apply to documentation builds. 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. 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-commenting 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/Documentation/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 correttamente, potete eseguire il programma ``kernel-doc`` con un livello di verbosità alto e senza che questo produca alcuna documentazione. Per esempio:: - scripts/kernel-doc -v -none drivers/foo/bar.c + tools/docs/kernel-doc -v -none drivers/foo/bar.c Il formato della documentazione è verificato della procedura di generazione del kernel quando viene richiesto di effettuare dei controlli extra con GCC:: @@ -378,7 +378,7 @@ distinguono in base al fatto che il nome della macro simile a funzione sia immediatamente seguito da una parentesi sinistra ('(') mentre in quelle simili a oggetti no. -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/kernel-doc``. Possono avere un elenco di parametri. Le macro simili a oggetti non hanno un elenco di parametri. @@ -595,7 +595,7 @@ documentazione presenti nel file sorgente (*source*). L'estensione kernel-doc fa parte dei sorgenti del kernel, la si può trovare 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 documentazione dai file sorgenti. 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:: - $ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | 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/Documentation/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É hace esto. 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ás detalles. +y ``tools/docs/kernel-doc`` para más detalles. El estilo preferido para comentarios largos (de varias líneas) es: diff --git a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst b/Documentation/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注释用 ``/**`` 作为开始标记。 ``kernel-doc`` 工具将提取 用详细模式和不生成实际输出来运行 ``kernel-doc`` 工具，可以验证文档注释的格式 是否正确。例如:: - scripts/kernel-doc -v -none drivers/foo/bar.c + tools/docs/kernel-doc -v -none drivers/foo/bar.c 当请求执行额外的gcc检查时，内核构建将验证文档格式:: @@ -473,7 +473,7 @@ doc: *title* 如果没有选项，kernel-doc指令将包含源文件中的所有文档注释。 kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/kerneldoc.py`` 。 -在内部，它使用 ``scripts/kernel-doc`` 脚本从源代码中提取文档注释。 +在内部，它使用 ``tools/docs/kernel-doc`` 脚本从源代码中提取文档注释。 .. _kernel_doc_zh: @@ -482,18 +482,18 @@ kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/k 如果您只想使用kernel-doc生成手册页，可以从内核git树这样做:: - $ scripts/kernel-doc -man \ + $ tools/docs/kernel-doc -man \ $(git grep -l '/\*\*' -- :^Documentation :^tools) \ | scripts/split-man.pl /tmp/man 一些旧版本的git不支持路径排除语法的某些变体。 以下命令之一可能适用于这些版本:: - $ scripts/kernel-doc -man \ + $ tools/docs/kernel-doc -man \ $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \ | scripts/split-man.pl /tmp/man - $ scripts/kernel-doc -man \ + $ tools/docs/kernel-doc -man \ $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \ | scripts/split-man.pl /tmp/man diff --git a/Documentation/translations/zh_CN/kbuild/kbuild.rst b/Documentation/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 变量（在某些架构中还包括内核配置）来猜测正确 KDOCFLAGS --------- 指定在构建过程中用于 kernel-doc 检查的额外（警告/错误）标志，查看 -scripts/kernel-doc 了解支持的标志。请注意，这目前不适用于文档构建。 +tools/docs/kernel-doc 了解支持的标志。请注意，这目前不适用于文档构建。 ARCH ---- diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/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 里这是提倡的做法，因为这样可以很简单的给读者提供 也可以加上它做这些事情的原因。 当注释内核 API 函数时，请使用 kernel-doc 格式。详见 -Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。 +Documentation/translations/zh_CN/doc-guide/index.rst 和 tools/docs/kernel-doc 。 长 (多行) 注释的首选风格是： diff --git a/Documentation/translations/zh_TW/process/coding-style.rst b/Documentation/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 裏這是提倡的做法，因爲這樣可以很簡單的給讀者提供 也可以加上它做這些事情的原因。 當註釋內核 API 函數時，請使用 kernel-doc 格式。詳見 -Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。 +Documentation/translations/zh_CN/doc-guide/index.rst 和 tools/docs/kernel-doc 。 長 (多行) 註釋的首選風格是： 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/ diff --git a/Makefile b/Makefile index 3cd00b62cde9..81a4ab11256c 100644 --- a/Makefile +++ b/Makefile @@ -460,7 +460,7 @@ HOSTPKG_CONFIG = pkg-config # the KERNELDOC macro needs to be exported, as scripts/Makefile.build # has a logic to call it -KERNELDOC = $(srctree)/scripts/kernel-doc.py +KERNELDOC = $(srctree)/tools/docs/kernel-doc export KERNELDOC KBUILD_USERHOSTCFLAGS := -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) += \ quiet_cmd_hdrtest = HDRTEST $(patsubst %.hdrtest,%.h,$@) cmd_hdrtest = $(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 $@ $(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/scripts/kernel-doc.py b/scripts/kernel-doc.py deleted file mode 100755 index 4e3b9cfe3fd7..000000000000 --- a/scripts/kernel-doc.py +++ /dev/null @@ -1,360 +0,0 @@ -#!/usr/bin/env python3 -# SPDX-License-Identifier: GPL-2.0 -# Copyright(c) 2025: Mauro Carvalho Chehab . -# -# pylint: disable=C0103,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 -# compilation with older Kernel versions. Due to that: -# - encoding line is needed here; -# - 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: -# -# Aditya Srivastava -# Akira Yokosawa -# Alexander A. Klimov -# Alexander Lobakin -# André Almeida -# Andy Shevchenko -# Anna-Maria Behnsen -# Armin Kuster -# Bart Van Assche -# Ben Hutchings -# Borislav Petkov -# Chen-Yu Tsai -# Coco Li -# Conchúr Navid -# Daniel Santos -# Danilo Cesar Lemes de Paula -# Dan Luedtke -# Donald Hunter -# Gabriel Krisman Bertazi -# Greg Kroah-Hartman -# Harvey Harrison -# Horia Geanta -# Ilya Dryomov -# Jakub Kicinski -# Jani Nikula -# Jason Baron -# Jason Gunthorpe -# Jérémy Bobbio -# Johannes Berg -# Johannes Weiner -# Jonathan Cameron -# Jonathan Corbet -# Jonathan Neuschäfer -# Kamil Rytarowski -# Kees Cook -# Laurent Pinchart -# Levin, Alexander (Sasha Levin) -# Linus Torvalds -# Lucas De Marchi -# Mark Rutland -# Markus Heiser -# Martin Waitz -# Masahiro Yamada -# Matthew Wilcox -# Mauro Carvalho Chehab -# Michal Wajdeczko -# Michael Zucchi -# Mike Rapoport -# Niklas Söderlund -# Nishanth Menon -# Paolo Bonzini -# Pavan Kumar Linga -# Pavel Pisa -# Peter Maydell -# Pierre-Louis Bossart -# Randy Dunlap -# Richard Kennedy -# Rich Walker -# Rolf Eike Beer -# Sakari Ailus -# Silvio Fricke -# Simon Huggins -# Tim Waugh -# Tomasz Warniełło -# Utkarsh Tripathi -# valdis.kletnieks@vt.edu -# Vegard Nossum -# Will Deacon -# Yacine Belkadi -# Yujie Liu - -""" -Print formatted kernel documentation to stdout. - -Read C language source or header FILEs, extract embedded -documentation comments, and print formatted documentation -to standard output. - -The documentation comments are identified by the ``/**`` -opening comment mark. - -See Documentation/doc-guide/kernel-doc.rst for the -documentation comment syntax. -""" - -import argparse -import logging -import os -import sys - -# Import Python modules - -LIB_DIR = "../tools/lib/python" -SRC_DIR = os.path.dirname(os.path.realpath(__file__)) - -sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) - -WERROR_RETURN_CODE = 3 - -DESC = """ -Read C language source or header FILEs, extract embedded documentation comments, -and print formatted documentation to standard output. - -The documentation comments are identified by the "/**" opening comment mark. - -See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax. -""" - -EXPORT_FILE_DESC = """ -Specify an additional FILE in which to look for EXPORT_SYMBOL information. - -May be used multiple times. -""" - -EXPORT_DESC = """ -Only output documentation for symbols that have been -exported using EXPORT_SYMBOL() and related macros in any input -FILE or -export-file FILE. -""" - -INTERNAL_DESC = """ -Only output documentation for symbols that have NOT been -exported using EXPORT_SYMBOL() and related macros in any input -FILE or -export-file FILE. -""" - -FUNCTION_DESC = """ -Only output documentation for the given function or DOC: section -title. All other functions and DOC: sections are ignored. - -May be used multiple times. -""" - -NOSYMBOL_DESC = """ -Exclude the specified symbol from the output documentation. - -May be used multiple times. -""" - -FILES_DESC = """ -Header and C source files to be parsed. -""" - -WARN_CONTENTS_BEFORE_SECTIONS_DESC = """ -Warn if there are contents before sections (deprecated). - -This option is kept just for backward-compatibility, but it does nothing, -neither here nor at the original Perl script. -""" - - -class MsgFormatter(logging.Formatter): - """Helper class to format warnings in a similar way to kernel-doc.pl.""" - - def format(self, record): - record.levelname = record.levelname.capitalize() - return logging.Formatter.format(self, record) - -def main(): - """ - 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 happened. - """ - - parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter, - description=DESC) - - # - # Normal arguments - # - parser.add_argument("-v", "-verbose", "--verbose", action="store_true", - help="Verbose output, more warnings and other information.") - - parser.add_argument("-d", "-debug", "--debug", action="store_true", - help="Enable debug messages") - - parser.add_argument("-M", "-modulename", "--modulename", - default="Kernel API", - help="Allow setting a module name at the output.") - - parser.add_argument("-l", "-enable-lineno", "--enable_lineno", - action="store_true", - help="Enable line number output (only in ReST mode)") - - # - # Arguments to control the warning behavior - # - parser.add_argument("-Wreturn", "--wreturn", action="store_true", - help="Warns about the lack of a return markup on functions.") - - parser.add_argument("-Wshort-desc", "-Wshort-description", "--wshort-desc", - action="store_true", - help="Warns if initial short description is missing") - - parser.add_argument("-Wcontents-before-sections", - "--wcontents-before-sections", action="store_true", - help=WARN_CONTENTS_BEFORE_SECTIONS_DESC) - - parser.add_argument("-Wall", "--wall", action="store_true", - help="Enable all types of warnings") - - parser.add_argument("-Werror", "--werror", action="store_true", - help="Treat warnings as errors.") - - parser.add_argument("-export-file", "--export-file", action='append', - help=EXPORT_FILE_DESC) - - # - # Output format mutually-exclusive group - # - out_group = parser.add_argument_group("Output format selection (mutually exclusive)") - - out_fmt = out_group.add_mutually_exclusive_group() - - out_fmt.add_argument("-m", "-man", "--man", action="store_true", - help="Output troff manual page format.") - out_fmt.add_argument("-r", "-rst", "--rst", action="store_true", - help="Output reStructuredText format (default).") - out_fmt.add_argument("-N", "-none", "--none", action="store_true", - help="Do not output documentation, only warnings.") - - # - # Output selection mutually-exclusive group - # - sel_group = parser.add_argument_group("Output selection (mutually exclusive)") - sel_mut = sel_group.add_mutually_exclusive_group() - - sel_mut.add_argument("-e", "-export", "--export", action='store_true', - help=EXPORT_DESC) - - sel_mut.add_argument("-i", "-internal", "--internal", action='store_true', - help=INTERNAL_DESC) - - sel_mut.add_argument("-s", "-function", "--symbol", action='append', - help=FUNCTION_DESC) - - # - # Those are valid for all 3 types of filter - # - parser.add_argument("-n", "-nosymbol", "--nosymbol", action='append', - help=NOSYMBOL_DESC) - - parser.add_argument("-D", "-no-doc-sections", "--no-doc-sections", - action='store_true', help="Don't output DOC sections") - - parser.add_argument("files", metavar="FILE", - nargs="+", help=FILES_DESC) - - args = parser.parse_args() - - if args.wall: - args.wreturn = True - args.wshort_desc = True - args.wcontents_before_sections = True - - logger = logging.getLogger() - - if not args.debug: - logger.setLevel(logging.INFO) - else: - logger.setLevel(logging.DEBUG) - - formatter = MsgFormatter('%(levelname)s: %(message)s') - - handler = logging.StreamHandler() - handler.setFormatter(formatter) - - logger.addHandler(handler) - - python_ver = sys.version_info[:2] - if python_ver < (3,6): - # - # Depending on the 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. Skipping checks") - sys.exit(0) - - sys.exit("Python 3.6 or later is required by kernel-doc. Aborting.") - - if python_ver < (3,7): - logger.warning("Python 3.7 or later is required for correct results") - - # - # Import kernel-doc libraries only after checking the Python version - # - from kdoc.kdoc_files import KernelFiles # pylint: disable=C0415 - from kdoc.kdoc_output import RestFormat, ManFormat # pylint: disable=C0415 - - if args.man: - out_style = ManFormat(modulename=args.modulename) - elif args.none: - out_style = None - else: - out_style = RestFormat() - - kfiles = KernelFiles(verbose=args.verbose, - out_style=out_style, werror=args.werror, - wreturn=args.wreturn, wshort_desc=args.wshort_desc, - wcontents_before_sections=args.wcontents_before_sections) - - kfiles.parse(args.files, export_file=args.export_file) - - for t in kfiles.msg(enable_lineno=args.enable_lineno, export=args.export, - internal=args.internal, symbol=args.symbol, - nosymbol=args.nosymbol, export_file=args.export_file, - no_doc_sections=args.no_doc_sections): - msg = t[1] - if msg: - print(msg) - - error_count = kfiles.errors - if not error_count: - sys.exit(0) - - if args.werror: - print("%s warnings as errors" % error_count) # pylint: disable=C0209 - sys.exit(WERROR_RETURN_CODE) - - if args.verbose: - print("%s errors" % error_count) # pylint: disable=C0209 - - sys.exit(0) - -# -# Call main method -# -if __name__ == "__main__": - main() 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=$(PYTHONDONTWRITEBYTECODE=1 scripts/kernel-doc -export "$file" 2>/dev/null) + str=$(PYTHONDONTWRITEBYTECODE=1 tools/docs/kernel-doc -export "$file" 2>/dev/null) if [[ -n "$str" ]]; then echo "$file" fi diff --git a/tools/docs/kernel-doc b/tools/docs/kernel-doc new file mode 100755 index 000000000000..a19a92566780 --- /dev/null +++ b/tools/docs/kernel-doc @@ -0,0 +1,360 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0 +# Copyright(c) 2025: Mauro Carvalho Chehab . +# +# pylint: disable=C0103,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 +# compilation with older Kernel versions. Due to that: +# - encoding line is needed here; +# - 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: +# +# Aditya Srivastava +# Akira Yokosawa +# Alexander A. Klimov +# Alexander Lobakin +# André Almeida +# Andy Shevchenko +# Anna-Maria Behnsen +# Armin Kuster +# Bart Van Assche +# Ben Hutchings +# Borislav Petkov +# Chen-Yu Tsai +# Coco Li +# Conchúr Navid +# Daniel Santos +# Danilo Cesar Lemes de Paula +# Dan Luedtke +# Donald Hunter +# Gabriel Krisman Bertazi +# Greg Kroah-Hartman +# Harvey Harrison +# Horia Geanta +# Ilya Dryomov +# Jakub Kicinski +# Jani Nikula +# Jason Baron +# Jason Gunthorpe +# Jérémy Bobbio +# Johannes Berg +# Johannes Weiner +# Jonathan Cameron +# Jonathan Corbet +# Jonathan Neuschäfer +# Kamil Rytarowski +# Kees Cook +# Laurent Pinchart +# Levin, Alexander (Sasha Levin) +# Linus Torvalds +# Lucas De Marchi +# Mark Rutland +# Markus Heiser +# Martin Waitz +# Masahiro Yamada +# Matthew Wilcox +# Mauro Carvalho Chehab +# Michal Wajdeczko +# Michael Zucchi +# Mike Rapoport +# Niklas Söderlund +# Nishanth Menon +# Paolo Bonzini +# Pavan Kumar Linga +# Pavel Pisa +# Peter Maydell +# Pierre-Louis Bossart +# Randy Dunlap +# Richard Kennedy +# Rich Walker +# Rolf Eike Beer +# Sakari Ailus +# Silvio Fricke +# Simon Huggins +# Tim Waugh +# Tomasz Warniełło +# Utkarsh Tripathi +# valdis.kletnieks@vt.edu +# Vegard Nossum +# Will Deacon +# Yacine Belkadi +# Yujie Liu + +""" +Print formatted kernel documentation to stdout. + +Read C language source or header FILEs, extract embedded +documentation comments, and print formatted documentation +to standard output. + +The documentation comments are identified by the ``/**`` +opening comment mark. + +See Documentation/doc-guide/kernel-doc.rst for the +documentation comment syntax. +""" + +import argparse +import logging +import os +import sys + +# Import Python modules + +LIB_DIR = "../lib/python" +SRC_DIR = os.path.dirname(os.path.realpath(__file__)) + +sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) + +WERROR_RETURN_CODE = 3 + +DESC = """ +Read C language source or header FILEs, extract embedded documentation comments, +and print formatted documentation to standard output. + +The documentation comments are identified by the "/**" opening comment mark. + +See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax. +""" + +EXPORT_FILE_DESC = """ +Specify an additional FILE in which to look for EXPORT_SYMBOL information. + +May be used multiple times. +""" + +EXPORT_DESC = """ +Only output documentation for symbols that have been +exported using EXPORT_SYMBOL() and related macros in any input +FILE or -export-file FILE. +""" + +INTERNAL_DESC = """ +Only output documentation for symbols that have NOT been +exported using EXPORT_SYMBOL() and related macros in any input +FILE or -export-file FILE. +""" + +FUNCTION_DESC = """ +Only output documentation for the given function or DOC: section +title. All other functions and DOC: sections are ignored. + +May be used multiple times. +""" + +NOSYMBOL_DESC = """ +Exclude the specified symbol from the output documentation. + +May be used multiple times. +""" + +FILES_DESC = """ +Header and C source files to be parsed. +""" + +WARN_CONTENTS_BEFORE_SECTIONS_DESC = """ +Warn if there are contents before sections (deprecated). + +This option is kept just for backward-compatibility, but it does nothing, +neither here nor at the original Perl script. +""" + + +class MsgFormatter(logging.Formatter): + """Helper class to format warnings in a similar way to kernel-doc.pl.""" + + def format(self, record): + record.levelname = record.levelname.capitalize() + return logging.Formatter.format(self, record) + +def main(): + """ + 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 happened. + """ + + parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter, + description=DESC) + + # + # Normal arguments + # + parser.add_argument("-v", "-verbose", "--verbose", action="store_true", + help="Verbose output, more warnings and other information.") + + parser.add_argument("-d", "-debug", "--debug", action="store_true", + help="Enable debug messages") + + parser.add_argument("-M", "-modulename", "--modulename", + default="Kernel API", + help="Allow setting a module name at the output.") + + parser.add_argument("-l", "-enable-lineno", "--enable_lineno", + action="store_true", + help="Enable line number output (only in ReST mode)") + + # + # Arguments to control the warning behavior + # + parser.add_argument("-Wreturn", "--wreturn", action="store_true", + help="Warns about the lack of a return markup on functions.") + + parser.add_argument("-Wshort-desc", "-Wshort-description", "--wshort-desc", + action="store_true", + help="Warns if initial short description is missing") + + parser.add_argument("-Wcontents-before-sections", + "--wcontents-before-sections", action="store_true", + help=WARN_CONTENTS_BEFORE_SECTIONS_DESC) + + parser.add_argument("-Wall", "--wall", action="store_true", + help="Enable all types of warnings") + + parser.add_argument("-Werror", "--werror", action="store_true", + help="Treat warnings as errors.") + + parser.add_argument("-export-file", "--export-file", action='append', + help=EXPORT_FILE_DESC) + + # + # Output format mutually-exclusive group + # + out_group = parser.add_argument_group("Output format selection (mutually exclusive)") + + out_fmt = out_group.add_mutually_exclusive_group() + + out_fmt.add_argument("-m", "-man", "--man", action="store_true", + help="Output troff manual page format.") + out_fmt.add_argument("-r", "-rst", "--rst", action="store_true", + help="Output reStructuredText format (default).") + out_fmt.add_argument("-N", "-none", "--none", action="store_true", + help="Do not output documentation, only warnings.") + + # + # Output selection mutually-exclusive group + # + sel_group = parser.add_argument_group("Output selection (mutually exclusive)") + sel_mut = sel_group.add_mutually_exclusive_group() + + sel_mut.add_argument("-e", "-export", "--export", action='store_true', + help=EXPORT_DESC) + + sel_mut.add_argument("-i", "-internal", "--internal", action='store_true', + help=INTERNAL_DESC) + + sel_mut.add_argument("-s", "-function", "--symbol", action='append', + help=FUNCTION_DESC) + + # + # Those are valid for all 3 types of filter + # + parser.add_argument("-n", "-nosymbol", "--nosymbol", action='append', + help=NOSYMBOL_DESC) + + parser.add_argument("-D", "-no-doc-sections", "--no-doc-sections", + action='store_true', help="Don't output DOC sections") + + parser.add_argument("files", metavar="FILE", + nargs="+", help=FILES_DESC) + + args = parser.parse_args() + + if args.wall: + args.wreturn = True + args.wshort_desc = True + args.wcontents_before_sections = True + + logger = logging.getLogger() + + if not args.debug: + logger.setLevel(logging.INFO) + else: + logger.setLevel(logging.DEBUG) + + formatter = MsgFormatter('%(levelname)s: %(message)s') + + handler = logging.StreamHandler() + handler.setFormatter(formatter) + + logger.addHandler(handler) + + python_ver = sys.version_info[:2] + if python_ver < (3,6): + # + # Depending on the 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. Skipping checks") + sys.exit(0) + + sys.exit("Python 3.6 or later is required by kernel-doc. Aborting.") + + if python_ver < (3,7): + logger.warning("Python 3.7 or later is required for correct results") + + # + # Import kernel-doc libraries only after checking the Python version + # + from kdoc.kdoc_files import KernelFiles # pylint: disable=C0415 + from kdoc.kdoc_output import RestFormat, ManFormat # pylint: disable=C0415 + + if args.man: + out_style = ManFormat(modulename=args.modulename) + elif args.none: + out_style = None + else: + out_style = RestFormat() + + kfiles = KernelFiles(verbose=args.verbose, + out_style=out_style, werror=args.werror, + wreturn=args.wreturn, wshort_desc=args.wshort_desc, + wcontents_before_sections=args.wcontents_before_sections) + + kfiles.parse(args.files, export_file=args.export_file) + + for t in kfiles.msg(enable_lineno=args.enable_lineno, export=args.export, + internal=args.internal, symbol=args.symbol, + nosymbol=args.nosymbol, export_file=args.export_file, + no_doc_sections=args.no_doc_sections): + msg = t[1] + if msg: + print(msg) + + error_count = kfiles.errors + if not error_count: + sys.exit(0) + + if args.werror: + print("%s warnings as errors" % error_count) # pylint: disable=C0209 + sys.exit(WERROR_RETURN_CODE) + + if args.verbose: + print("%s errors" % error_count) # pylint: disable=C0209 + + sys.exit(0) + +# +# Call main method +# +if __name__ == "__main__": + main() diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper index 7a5fcef25429..cb2a5005e633 100755 --- a/tools/docs/sphinx-build-wrapper +++ b/tools/docs/sphinx-build-wrapper @@ -246,7 +246,7 @@ class SphinxBuilder: # self.sphinxbuild = os.environ.get("SPHINXBUILD", "sphinx-build") self.kerneldoc = self.get_path(os.environ.get("KERNELDOC", - "scripts/kernel-doc.py")) + "tools/docs/kernel-doc")) self.builddir = self.get_path(builddir, use_cwd=True, abs_path=True) # -- cgit v1.2.3