# 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):
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::
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.
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:
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
When commenting the kernel API functions, please use the kernel-doc format.
See the files at :ref:`Documentation/doc-guide/ <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.
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::
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.
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
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
Al comentar las funciones de la API del kernel, utilice el formato
kernel-doc. Consulte los archivos en :ref:`Documentation/doc-guide/ <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:
用详细模式和不生成实际输出来运行 ``kernel-doc`` 工具，可以验证文档注释的格式
是否正确。例如::
- scripts/kernel-doc -v -none drivers/foo/bar.c
+ tools/docs/kernel-doc -v -none drivers/foo/bar.c
当请求执行额外的gcc检查时，内核构建将验证文档格式::
如果没有选项，kernel-doc指令将包含源文件中的所有文档注释。
kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/kerneldoc.py`` 。
-在内部，它使用 ``scripts/kernel-doc`` 脚本从源代码中提取文档注释。
+在内部，它使用 ``tools/docs/kernel-doc`` 脚本从源代码中提取文档注释。
.. _kernel_doc_zh:
如果您只想使用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
KDOCFLAGS
---------
指定在构建过程中用于 kernel-doc 检查的额外（警告/错误）标志，查看
-scripts/kernel-doc 了解支持的标志。请注意，这目前不适用于文档构建。
+tools/docs/kernel-doc 了解支持的标志。请注意，这目前不适用于文档构建。
ARCH
----
也可以加上它做这些事情的原因。
当注释内核 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 。
长 (多行) 注释的首选风格是：
也可以加上它做這些事情的原因。
當註釋內核 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 。
長 (多行) 註釋的首選風格是：
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
L: linux-doc@vger.kernel.org
S: Maintained
F: Documentation/sphinx/
-F: scripts/kernel-doc*
F: tools/lib/python/*
F: tools/docs/
# 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 \
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)
+++ /dev/null
-kernel-doc.py
\ No newline at end of file
+++ /dev/null
-#!/usr/bin/env python3
-# SPDX-License-Identifier: GPL-2.0
-# Copyright(c) 2025: Mauro Carvalho Chehab <mchehab@kernel.org>.
-#
-# 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 <yashsri421@gmail.com>
-# Akira Yokosawa <akiyks@gmail.com>
-# Alexander A. Klimov <grandmaster@al2klimov.de>
-# Alexander Lobakin <aleksander.lobakin@intel.com>
-# André Almeida <andrealmeid@igalia.com>
-# Andy Shevchenko <andriy.shevchenko@linux.intel.com>
-# Anna-Maria Behnsen <anna-maria@linutronix.de>
-# Armin Kuster <akuster@mvista.com>
-# Bart Van Assche <bart.vanassche@sandisk.com>
-# Ben Hutchings <ben@decadent.org.uk>
-# Borislav Petkov <bbpetkov@yahoo.de>
-# Chen-Yu Tsai <wenst@chromium.org>
-# Coco Li <lixiaoyan@google.com>
-# Conchúr Navid <conchur@web.de>
-# Daniel Santos <daniel.santos@pobox.com>
-# Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>
-# Dan Luedtke <mail@danrl.de>
-# Donald Hunter <donald.hunter@gmail.com>
-# Gabriel Krisman Bertazi <krisman@collabora.co.uk>
-# Greg Kroah-Hartman <gregkh@linuxfoundation.org>
-# Harvey Harrison <harvey.harrison@gmail.com>
-# Horia Geanta <horia.geanta@freescale.com>
-# Ilya Dryomov <idryomov@gmail.com>
-# Jakub Kicinski <kuba@kernel.org>
-# Jani Nikula <jani.nikula@intel.com>
-# Jason Baron <jbaron@redhat.com>
-# Jason Gunthorpe <jgg@nvidia.com>
-# Jérémy Bobbio <lunar@debian.org>
-# Johannes Berg <johannes.berg@intel.com>
-# Johannes Weiner <hannes@cmpxchg.org>
-# Jonathan Cameron <Jonathan.Cameron@huawei.com>
-# Jonathan Corbet <corbet@lwn.net>
-# Jonathan Neuschäfer <j.neuschaefer@gmx.net>
-# Kamil Rytarowski <n54@gmx.com>
-# Kees Cook <kees@kernel.org>
-# Laurent Pinchart <laurent.pinchart@ideasonboard.com>
-# Levin, Alexander (Sasha Levin) <alexander.levin@verizon.com>
-# Linus Torvalds <torvalds@linux-foundation.org>
-# Lucas De Marchi <lucas.demarchi@profusion.mobi>
-# Mark Rutland <mark.rutland@arm.com>
-# Markus Heiser <markus.heiser@darmarit.de>
-# Martin Waitz <tali@admingilde.org>
-# Masahiro Yamada <masahiroy@kernel.org>
-# Matthew Wilcox <willy@infradead.org>
-# Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
-# Michal Wajdeczko <michal.wajdeczko@intel.com>
-# Michael Zucchi
-# Mike Rapoport <rppt@linux.ibm.com>
-# Niklas Söderlund <niklas.soderlund@corigine.com>
-# Nishanth Menon <nm@ti.com>
-# Paolo Bonzini <pbonzini@redhat.com>
-# Pavan Kumar Linga <pavan.kumar.linga@intel.com>
-# Pavel Pisa <pisa@cmp.felk.cvut.cz>
-# Peter Maydell <peter.maydell@linaro.org>
-# Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com>
-# Randy Dunlap <rdunlap@infradead.org>
-# Richard Kennedy <richard@rsk.demon.co.uk>
-# Rich Walker <rw@shadow.org.uk>
-# Rolf Eike Beer <eike-kernel@sf-tec.de>
-# Sakari Ailus <sakari.ailus@linux.intel.com>
-# Silvio Fricke <silvio.fricke@gmail.com>
-# Simon Huggins
-# Tim Waugh <twaugh@redhat.com>
-# Tomasz Warniełło <tomasz.warniello@gmail.com>
-# Utkarsh Tripathi <utripathi2002@gmail.com>
-# valdis.kletnieks@vt.edu <valdis.kletnieks@vt.edu>
-# Vegard Nossum <vegard.nossum@oracle.com>
-# Will Deacon <will.deacon@arm.com>
-# Yacine Belkadi <yacine.belkadi.1@gmail.com>
-# Yujie Liu <yujie.liu@intel.com>
-
-"""
-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()
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
--- /dev/null
+#!/usr/bin/env python3
+# SPDX-License-Identifier: GPL-2.0
+# Copyright(c) 2025: Mauro Carvalho Chehab <mchehab@kernel.org>.
+#
+# 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 <yashsri421@gmail.com>
+# Akira Yokosawa <akiyks@gmail.com>
+# Alexander A. Klimov <grandmaster@al2klimov.de>
+# Alexander Lobakin <aleksander.lobakin@intel.com>
+# André Almeida <andrealmeid@igalia.com>
+# Andy Shevchenko <andriy.shevchenko@linux.intel.com>
+# Anna-Maria Behnsen <anna-maria@linutronix.de>
+# Armin Kuster <akuster@mvista.com>
+# Bart Van Assche <bart.vanassche@sandisk.com>
+# Ben Hutchings <ben@decadent.org.uk>
+# Borislav Petkov <bbpetkov@yahoo.de>
+# Chen-Yu Tsai <wenst@chromium.org>
+# Coco Li <lixiaoyan@google.com>
+# Conchúr Navid <conchur@web.de>
+# Daniel Santos <daniel.santos@pobox.com>
+# Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>
+# Dan Luedtke <mail@danrl.de>
+# Donald Hunter <donald.hunter@gmail.com>
+# Gabriel Krisman Bertazi <krisman@collabora.co.uk>
+# Greg Kroah-Hartman <gregkh@linuxfoundation.org>
+# Harvey Harrison <harvey.harrison@gmail.com>
+# Horia Geanta <horia.geanta@freescale.com>
+# Ilya Dryomov <idryomov@gmail.com>
+# Jakub Kicinski <kuba@kernel.org>
+# Jani Nikula <jani.nikula@intel.com>
+# Jason Baron <jbaron@redhat.com>
+# Jason Gunthorpe <jgg@nvidia.com>
+# Jérémy Bobbio <lunar@debian.org>
+# Johannes Berg <johannes.berg@intel.com>
+# Johannes Weiner <hannes@cmpxchg.org>
+# Jonathan Cameron <Jonathan.Cameron@huawei.com>
+# Jonathan Corbet <corbet@lwn.net>
+# Jonathan Neuschäfer <j.neuschaefer@gmx.net>
+# Kamil Rytarowski <n54@gmx.com>
+# Kees Cook <kees@kernel.org>
+# Laurent Pinchart <laurent.pinchart@ideasonboard.com>
+# Levin, Alexander (Sasha Levin) <alexander.levin@verizon.com>
+# Linus Torvalds <torvalds@linux-foundation.org>
+# Lucas De Marchi <lucas.demarchi@profusion.mobi>
+# Mark Rutland <mark.rutland@arm.com>
+# Markus Heiser <markus.heiser@darmarit.de>
+# Martin Waitz <tali@admingilde.org>
+# Masahiro Yamada <masahiroy@kernel.org>
+# Matthew Wilcox <willy@infradead.org>
+# Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
+# Michal Wajdeczko <michal.wajdeczko@intel.com>
+# Michael Zucchi
+# Mike Rapoport <rppt@linux.ibm.com>
+# Niklas Söderlund <niklas.soderlund@corigine.com>
+# Nishanth Menon <nm@ti.com>
+# Paolo Bonzini <pbonzini@redhat.com>
+# Pavan Kumar Linga <pavan.kumar.linga@intel.com>
+# Pavel Pisa <pisa@cmp.felk.cvut.cz>
+# Peter Maydell <peter.maydell@linaro.org>
+# Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com>
+# Randy Dunlap <rdunlap@infradead.org>
+# Richard Kennedy <richard@rsk.demon.co.uk>
+# Rich Walker <rw@shadow.org.uk>
+# Rolf Eike Beer <eike-kernel@sf-tec.de>
+# Sakari Ailus <sakari.ailus@linux.intel.com>
+# Silvio Fricke <silvio.fricke@gmail.com>
+# Simon Huggins
+# Tim Waugh <twaugh@redhat.com>
+# Tomasz Warniełło <tomasz.warniello@gmail.com>
+# Utkarsh Tripathi <utripathi2002@gmail.com>
+# valdis.kletnieks@vt.edu <valdis.kletnieks@vt.edu>
+# Vegard Nossum <vegard.nossum@oracle.com>
+# Will Deacon <will.deacon@arm.com>
+# Yacine Belkadi <yacine.belkadi.1@gmail.com>
+# Yujie Liu <yujie.liu@intel.com>
+
+"""
+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()
#
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)
#
projects / linux-2.6-microblaze.git / commitdiff