github-mirror/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux.git synced 2026-05-23 14:42:08 +02:00
Code Issues Actions Packages Projects Releases Wiki Activity Graph

docs: kdoc: move kernel-doc to tools/docs

Browse Source 
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 <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <311d17e403524349940a8b12de6b5e91e554b1f4.1768823489.git.mchehab+huawei@kernel.org>
This commit is contained in:
Jonathan Corbet 2026-01-19 13:05:01 +01:00
parent 24f984aa11
commit eba6ffd126
17 changed files with 25 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Documentation/conf.py
View File

@ -585,7 +585,7 @@ pdf_documents = [
# kernel-doc extension configuration for running Sphinx directly (e.g. by Read # 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 # the Docs). In a normal build, these are supplied from the Makefile via command
# line arguments. # line arguments.
kerneldoc_bin = "../scripts/kernel-doc.py" kerneldoc_bin = "../tools/docs/kernel-doc" # Not used now
kerneldoc_srctree = ".." kerneldoc_srctree = ".."
def setup(app): def setup(app):

8
Documentation/doc-guide/kernel-doc.rst
View File

@ -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 output generation may be used to verify proper formatting of the
documentation comments. For example:: 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 The documentation format of ``.c`` files is also verified by the kernel build
when it is requested to perform extra gcc checks:: 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 left parenthesis ('(') for function-like macros or not followed by one
for object-like macros. 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 They may have a parameter list. Object-like macros have do not have a
parameter list. parameter list.
@ -596,8 +596,8 @@ from the source file.
The kernel-doc extension is included in the kernel source tree, at The kernel-doc extension is included in the kernel source tree, at
``Documentation/sphinx/kerneldoc.py``. Internally, it uses the ``Documentation/sphinx/kerneldoc.py``. Internally, it uses the
``scripts/kernel-doc`` script to extract the documentation comments from the ``tools/docs/kernel-doc`` script to extract the documentation comments from
source. the source.
.. _kernel_doc: .. _kernel_doc:

2
Documentation/kbuild/kbuild.rst
View File

@ -180,7 +180,7 @@ architecture.
KDOCFLAGS KDOCFLAGS
--------- ---------
Specify extra (warning/error) flags for kernel-doc checks during the build, 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. (currently) apply to documentation builds.
ARCH ARCH

2
Documentation/process/coding-style.rst
View File

@ -614,7 +614,7 @@ it.
When commenting the kernel API functions, please use the kernel-doc format. When commenting the kernel API functions, please use the kernel-doc format.
See the files at :ref:`Documentation/doc-guide/ <doc_guide>` and 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 applies to kernel-doc comments all the same. Do not add boilerplate
kernel-doc which simply reiterates what's obvious from the signature kernel-doc which simply reiterates what's obvious from the signature
of the function. of the function.

8
Documentation/translations/it_IT/doc-guide/kernel-doc.rst
View File

@ -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 eseguire il programma ``kernel-doc`` con un livello di verbosità alto e senza
che questo produca alcuna documentazione. Per esempio:: 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 Il formato della documentazione è verificato della procedura di generazione
del kernel quando viene richiesto di effettuare dei controlli extra con GCC:: 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 immediatamente seguito da una parentesi sinistra ('(') mentre in quelle simili a
oggetti no. 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 Possono avere un elenco di parametri. Le macro simili a oggetti non hanno un
elenco di parametri. 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 L'estensione kernel-doc fa parte dei sorgenti del kernel, la si può trovare
in ``Documentation/sphinx/kerneldoc.py``. Internamente, viene utilizzato 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. dai file sorgenti.
Come utilizzare kernel-doc per generare pagine man 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 Se volete utilizzare kernel-doc solo per generare delle pagine man, potete
farlo direttamente dai sorgenti del kernel:: 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

2
Documentation/translations/sp_SP/process/coding-style.rst
View File

@ -633,7 +633,7 @@ posiblemente POR QUÉ hace esto.
Al comentar las funciones de la API del kernel, utilice el formato Al comentar las funciones de la API del kernel, utilice el formato
kernel-doc. Consulte los archivos en :ref:`Documentation/doc-guide/ <doc_guide>` 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: El estilo preferido para comentarios largos (de varias líneas) es:

10
Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
View File

@ -43,7 +43,7 @@ kernel-doc注释用 ``/**`` 作为开始标记。 ``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检查时，内核构建将验证文档格式:: 当请求执行额外的gcc检查时，内核构建将验证文档格式::
@ -473,7 +473,7 @@ doc: *title*
如果没有选项，kernel-doc指令将包含源文件中的所有文档注释。 如果没有选项，kernel-doc指令将包含源文件中的所有文档注释。
kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/kerneldoc.py`` 。 kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/kerneldoc.py`` 。
在内部，它使用 ``scripts/kernel-doc`` 脚本从源代码中提取文档注释。 在内部，它使用 ``tools/docs/kernel-doc`` 脚本从源代码中提取文档注释。
.. _kernel_doc_zh: .. _kernel_doc_zh:
@ -482,18 +482,18 @@ kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/k
如果您只想使用kernel-doc生成手册页，可以从内核git树这样做:: 如果您只想使用kernel-doc生成手册页，可以从内核git树这样做::
$ scripts/kernel-doc -man \ $ tools/docs/kernel-doc -man \
$(git grep -l '/\*\*' -- :^Documentation :^tools) \ $(git grep -l '/\*\*' -- :^Documentation :^tools) \
| scripts/split-man.pl /tmp/man | scripts/split-man.pl /tmp/man
一些旧版本的git不支持路径排除语法的某些变体。 一些旧版本的git不支持路径排除语法的某些变体。
以下命令之一可能适用于这些版本:: 以下命令之一可能适用于这些版本::
$ scripts/kernel-doc -man \ $ tools/docs/kernel-doc -man \
$(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \ $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
| scripts/split-man.pl /tmp/man | scripts/split-man.pl /tmp/man
$ scripts/kernel-doc -man \ $ tools/docs/kernel-doc -man \
$(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \ $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
| scripts/split-man.pl /tmp/man | scripts/split-man.pl /tmp/man

2
Documentation/translations/zh_CN/kbuild/kbuild.rst
View File

@ -174,7 +174,7 @@ UTS_MACHINE 变量（在某些架构中还包括内核配置）来猜测正确
KDOCFLAGS KDOCFLAGS
--------- ---------
指定在构建过程中用于 kernel-doc 检查的额外（警告/错误）标志，查看 指定在构建过程中用于 kernel-doc 检查的额外（警告/错误）标志，查看
scripts/kernel-doc 了解支持的标志。请注意，这目前不适用于文档构建。 tools/docs/kernel-doc 了解支持的标志。请注意，这目前不适用于文档构建。
ARCH ARCH
---- ----

2
Documentation/translations/zh_CN/process/coding-style.rst
View File

@ -545,7 +545,7 @@ Linux 里这是提倡的做法，因为这样可以很简单的给读者提供
也可以加上它做这些事情的原因。 也可以加上它做这些事情的原因。
当注释内核 API 函数时，请使用 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 。
长 (多行) 注释的首选风格是： 长 (多行) 注释的首选风格是：

2
Documentation/translations/zh_TW/process/coding-style.rst
View File

@ -548,7 +548,7 @@ Linux 裏這是提倡的做法，因爲這樣可以很簡單的給讀者提供
也可以加上它做這些事情的原因。 也可以加上它做這些事情的原因。
當註釋內核 API 函數時，請使用 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 。
長 (多行) 註釋的首選風格是： 長 (多行) 註釋的首選風格是：

2
MAINTAINERS
View File

@ -7523,7 +7523,6 @@ S: Maintained
P: Documentation/doc-guide/maintainer-profile.rst P: Documentation/doc-guide/maintainer-profile.rst
T: git git://git.lwn.net/linux.git docs-next T: git git://git.lwn.net/linux.git docs-next
F: Documentation/ F: Documentation/
F: scripts/kernel-doc*
F: tools/lib/python/* F: tools/lib/python/*
F: tools/docs/ F: tools/docs/
F: tools/net/ynl/pyynl/lib/doc_generator.py F: tools/net/ynl/pyynl/lib/doc_generator.py
@ -7561,7 +7560,6 @@ M: Mauro Carvalho Chehab <mchehab@kernel.org>
L: linux-doc@vger.kernel.org L: linux-doc@vger.kernel.org
S: Maintained S: Maintained
F: Documentation/sphinx/ F: Documentation/sphinx/
F: scripts/kernel-doc*
F: tools/lib/python/* F: tools/lib/python/*
F: tools/docs/ F: tools/docs/

2
Makefile
View File

@ -460,7 +460,7 @@ HOSTPKG_CONFIG = pkg-config
# the KERNELDOC macro needs to be exported, as scripts/Makefile.build # the KERNELDOC macro needs to be exported, as scripts/Makefile.build
# has a logic to call it # has a logic to call it
KERNELDOC = $(srctree)/scripts/kernel-doc.py KERNELDOC = $(srctree)/tools/docs/kernel-doc
export KERNELDOC export KERNELDOC
KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \ KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \

2
drivers/gpu/drm/i915/Makefile
View File

@ -443,7 +443,7 @@ always-$(CONFIG_DRM_I915_WERROR) += \
quiet_cmd_hdrtest = HDRTEST $(patsubst %.hdrtest,%.h,$@) 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 $<; \ 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 $(obj)/%.hdrtest: $(src)/%.h FORCE
$(call if_changed_dep,hdrtest) $(call if_changed_dep,hdrtest)

1
scripts/kernel-doc
View File

@ -1 +0,0 @@
kernel-doc.py

2
tools/docs/find-unused-docs.sh
View File

@ -54,7 +54,7 @@ for file in `find $1 -name '*.c'`; do
if [[ ${FILES_INCLUDED[$file]+_} ]]; then if [[ ${FILES_INCLUDED[$file]+_} ]]; then
continue; continue;
fi 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 if [[ -n "$str" ]]; then
echo "$file" echo "$file"
fi fi

2
scripts/kernel-doc.py → tools/docs/kernel-doc
View File

@ -108,7 +108,7 @@ import sys
# Import Python modules # Import Python modules
LIB_DIR = "../tools/lib/python" LIB_DIR = "../lib/python"
SRC_DIR = os.path.dirname(os.path.realpath(__file__)) SRC_DIR = os.path.dirname(os.path.realpath(__file__))
sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR))

2
tools/docs/sphinx-build-wrapper
View File

@ -246,7 +246,7 @@ class SphinxBuilder:
# #
self.sphinxbuild = os.environ.get("SPHINXBUILD", "sphinx-build") self.sphinxbuild = os.environ.get("SPHINXBUILD", "sphinx-build")
self.kerneldoc = self.get_path(os.environ.get("KERNELDOC", 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) self.builddir = self.get_path(builddir, use_cwd=True, abs_path=True)
# #