Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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 <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <311d17e403524349940a8b12de6b5e91e554b1f4.1768823489.git.mchehab+huawei@kernel.org>
+25
-27
+1
-1
Documentation/conf.py
+1
-1
Documentation/conf.py
···
585
585
# kernel-doc extension configuration for running Sphinx directly (e.g. by Read
586
586
# the Docs). In a normal build, these are supplied from the Makefile via command
587
587
# line arguments.
588
-
kerneldoc_bin = "../scripts/kernel-doc.py"
588
+
kerneldoc_bin = "../tools/docs/kernel-doc" # Not used now
589
589
kerneldoc_srctree = ".."
590
590
591
591
def setup(app):
+4
-4
Documentation/doc-guide/kernel-doc.rst
+4
-4
Documentation/doc-guide/kernel-doc.rst
···
54
54
output generation may be used to verify proper formatting of the
55
55
documentation comments. For example::
56
56
57
-
scripts/kernel-doc -v -none drivers/foo/bar.c
57
+
tools/docs/kernel-doc -v -none drivers/foo/bar.c
58
58
59
59
The documentation format of ``.c`` files is also verified by the kernel build
60
60
when it is requested to perform extra gcc checks::
···
365
365
left parenthesis ('(') for function-like macros or not followed by one
366
366
for object-like macros.
367
367
368
-
Function-like macros are handled like functions by ``scripts/kernel-doc``.
368
+
Function-like macros are handled like functions by ``tools/docs/kernel-doc``.
369
369
They may have a parameter list. Object-like macros have do not have a
370
370
parameter list.
371
371
···
596
596
597
597
The kernel-doc extension is included in the kernel source tree, at
598
598
``Documentation/sphinx/kerneldoc.py``. Internally, it uses the
599
-
``scripts/kernel-doc`` script to extract the documentation comments from the
600
-
source.
599
+
``tools/docs/kernel-doc`` script to extract the documentation comments from
600
+
the source.
601
601
602
602
.. _kernel_doc:
603
603
+1
-1
Documentation/kbuild/kbuild.rst
+1
-1
Documentation/kbuild/kbuild.rst
···
180
180
KDOCFLAGS
181
181
---------
182
182
Specify extra (warning/error) flags for kernel-doc checks during the build,
183
-
see scripts/kernel-doc for which flags are supported. Note that this doesn't
183
+
see tools/docs/kernel-doc for which flags are supported. Note that this doesn't
184
184
(currently) apply to documentation builds.
185
185
186
186
ARCH
+1
-1
Documentation/process/coding-style.rst
+1
-1
Documentation/process/coding-style.rst
···
614
614
615
615
When commenting the kernel API functions, please use the kernel-doc format.
616
616
See the files at :ref:`Documentation/doc-guide/ <doc_guide>` and
617
-
``scripts/kernel-doc`` for details. Note that the danger of over-commenting
617
+
``tools/docs/kernel-doc`` for details. Note that the danger of over-commenting
618
618
applies to kernel-doc comments all the same. Do not add boilerplate
619
619
kernel-doc which simply reiterates what's obvious from the signature
620
620
of the function.
+4
-4
Documentation/translations/it_IT/doc-guide/kernel-doc.rst
+4
-4
Documentation/translations/it_IT/doc-guide/kernel-doc.rst
···
80
80
eseguire il programma ``kernel-doc`` con un livello di verbosità alto e senza
81
81
che questo produca alcuna documentazione. Per esempio::
82
82
83
-
scripts/kernel-doc -v -none drivers/foo/bar.c
83
+
tools/docs/kernel-doc -v -none drivers/foo/bar.c
84
84
85
85
Il formato della documentazione è verificato della procedura di generazione
86
86
del kernel quando viene richiesto di effettuare dei controlli extra con GCC::
···
378
378
immediatamente seguito da una parentesi sinistra ('(') mentre in quelle simili a
379
379
oggetti no.
380
380
381
-
Le macro simili a funzioni sono gestite come funzioni da ``scripts/kernel-doc``.
381
+
Le macro simili a funzioni sono gestite come funzioni da ``tools/docs/kernel-doc``.
382
382
Possono avere un elenco di parametri. Le macro simili a oggetti non hanno un
383
383
elenco di parametri.
384
384
···
595
595
596
596
L'estensione kernel-doc fa parte dei sorgenti del kernel, la si può trovare
597
597
in ``Documentation/sphinx/kerneldoc.py``. Internamente, viene utilizzato
598
-
lo script ``scripts/kernel-doc`` per estrarre i commenti di documentazione
598
+
lo script ``tools/docs/kernel-doc`` per estrarre i commenti di documentazione
599
599
dai file sorgenti.
600
600
601
601
Come utilizzare kernel-doc per generare pagine man
···
604
604
Se volete utilizzare kernel-doc solo per generare delle pagine man, potete
605
605
farlo direttamente dai sorgenti del kernel::
606
606
607
-
$ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man
607
+
$ tools/docs/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man
+1
-1
Documentation/translations/sp_SP/process/coding-style.rst
+1
-1
Documentation/translations/sp_SP/process/coding-style.rst
···
633
633
634
634
Al comentar las funciones de la API del kernel, utilice el formato
635
635
kernel-doc. Consulte los archivos en :ref:`Documentation/doc-guide/ <doc_guide>`
636
-
y ``scripts/kernel-doc`` para más detalles.
636
+
y ``tools/docs/kernel-doc`` para más detalles.
637
637
638
638
El estilo preferido para comentarios largos (de varias líneas) es:
639
639
+5
-5
Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
+5
-5
Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
···
43
43
用详细模式和不生成实际输出来运行 ``kernel-doc`` 工具，可以验证文档注释的格式
44
44
是否正确。例如::
45
45
46
-
scripts/kernel-doc -v -none drivers/foo/bar.c
46
+
tools/docs/kernel-doc -v -none drivers/foo/bar.c
47
47
48
48
当请求执行额外的gcc检查时，内核构建将验证文档格式::
49
49
···
473
473
如果没有选项，kernel-doc指令将包含源文件中的所有文档注释。
474
474
475
475
kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/kerneldoc.py`` 。
476
-
在内部，它使用 ``scripts/kernel-doc`` 脚本从源代码中提取文档注释。
476
+
在内部，它使用 ``tools/docs/kernel-doc`` 脚本从源代码中提取文档注释。
477
477
478
478
.. _kernel_doc_zh:
479
479
···
482
482
483
483
如果您只想使用kernel-doc生成手册页，可以从内核git树这样做::
484
484
485
-
$ scripts/kernel-doc -man \
485
+
$ tools/docs/kernel-doc -man \
486
486
$(git grep -l '/\*\*' -- :^Documentation :^tools) \
487
487
| scripts/split-man.pl /tmp/man
488
488
489
489
一些旧版本的git不支持路径排除语法的某些变体。
490
490
以下命令之一可能适用于这些版本::
491
491
492
-
$ scripts/kernel-doc -man \
492
+
$ tools/docs/kernel-doc -man \
493
493
$(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
494
494
| scripts/split-man.pl /tmp/man
495
495
496
-
$ scripts/kernel-doc -man \
496
+
$ tools/docs/kernel-doc -man \
497
497
$(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
498
498
| scripts/split-man.pl /tmp/man
499
499
+1
-1
Documentation/translations/zh_CN/kbuild/kbuild.rst
+1
-1
Documentation/translations/zh_CN/kbuild/kbuild.rst
+1
-1
Documentation/translations/zh_CN/process/coding-style.rst
+1
-1
Documentation/translations/zh_CN/process/coding-style.rst
+1
-1
Documentation/translations/zh_TW/process/coding-style.rst
+1
-1
Documentation/translations/zh_TW/process/coding-style.rst
-2
MAINTAINERS
-2
MAINTAINERS
···
7523
7523
P: Documentation/doc-guide/maintainer-profile.rst
7524
7524
T: git git://git.lwn.net/linux.git docs-next
7525
7525
F: Documentation/
7526
-
F: scripts/kernel-doc*
7527
7526
F: tools/lib/python/*
7528
7527
F: tools/docs/
7529
7528
F: tools/net/ynl/pyynl/lib/doc_generator.py
···
7560
7561
L: linux-doc@vger.kernel.org
7561
7562
S: Maintained
7562
7563
F: Documentation/sphinx/
7563
-
F: scripts/kernel-doc*
7564
7564
F: tools/lib/python/*
7565
7565
F: tools/docs/
7566
7566
+1
-1
Makefile
+1
-1
Makefile
···
460
460
461
461
# the KERNELDOC macro needs to be exported, as scripts/Makefile.build
462
462
# has a logic to call it
463
-
KERNELDOC = $(srctree)/scripts/kernel-doc.py
463
+
KERNELDOC = $(srctree)/tools/docs/kernel-doc
464
464
export KERNELDOC
465
465
466
466
KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \
+1
-1
drivers/gpu/drm/i915/Makefile
+1
-1
drivers/gpu/drm/i915/Makefile
···
443
443
444
444
quiet_cmd_hdrtest = HDRTEST $(patsubst %.hdrtest,%.h,$@)
445
445
cmd_hdrtest = $(CC) $(filter-out $(CFLAGS_GCOV), $(c_flags)) -S -o /dev/null -x c /dev/null -include $<; \
446
-
$(srctree)/scripts/kernel-doc -none -Werror $<; touch $@
446
+
$(KERNELDOC) -none -Werror $<; touch $@
447
447
448
448
$(obj)/%.hdrtest: $(src)/%.h FORCE
449
449
$(call if_changed_dep,hdrtest)
+1
-1
scripts/kernel-doc.py
tools/docs/kernel-doc
+1
-1
scripts/kernel-doc.py
tools/docs/kernel-doc
+1
-1
tools/docs/find-unused-docs.sh
+1
-1
tools/docs/find-unused-docs.sh
···
54
54
if [[ ${FILES_INCLUDED[$file]+_} ]]; then
55
55
continue;
56
56
fi
57
-
str=$(PYTHONDONTWRITEBYTECODE=1 scripts/kernel-doc -export "$file" 2>/dev/null)
57
+
str=$(PYTHONDONTWRITEBYTECODE=1 tools/docs/kernel-doc -export "$file" 2>/dev/null)
58
58
if [[ -n "$str" ]]; then
59
59
echo "$file"
60
60
fi
+1
-1
tools/docs/sphinx-build-wrapper
+1
-1
tools/docs/sphinx-build-wrapper
···
246
246
#
247
247
self.sphinxbuild = os.environ.get("SPHINXBUILD", "sphinx-build")
248
248
self.kerneldoc = self.get_path(os.environ.get("KERNELDOC",
249
-
"scripts/kernel-doc.py"))
249
+
"tools/docs/kernel-doc"))
250
250
self.builddir = self.get_path(builddir, use_cwd=True, abs_path=True)
251
251
252
252
#