# 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
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
# Import Python modules
-LIB_DIR = "../tools/lib/python"
+LIB_DIR = "../lib/python"
SRC_DIR = os.path.dirname(os.path.realpath(__file__))
sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR))
#
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 / thirdparty / kernel / linux.git / commitdiff
