Skip to content

Commit eba6ffd

Browse files
author
Jonathan Corbet
committed
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>
1 parent 24f984a commit eba6ffd

17 files changed

Lines changed: 25 additions & 28 deletions

File tree

Documentation/conf.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -585,7 +585,7 @@ def get_cline_version():
585585
# kernel-doc extension configuration for running Sphinx directly (e.g. by Read
586586
# the Docs). In a normal build, these are supplied from the Makefile via command
587587
# line arguments.
588-
kerneldoc_bin = "../scripts/kernel-doc.py"
588+
kerneldoc_bin = "../tools/docs/kernel-doc" # Not used now
589589
kerneldoc_srctree = ".."
590590

591591
def setup(app):

Documentation/doc-guide/kernel-doc.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ Running the ``kernel-doc`` tool with increased verbosity and without actual
5454
output generation may be used to verify proper formatting of the
5555
documentation comments. For example::
5656

57-
scripts/kernel-doc -v -none drivers/foo/bar.c
57+
tools/docs/kernel-doc -v -none drivers/foo/bar.c
5858

5959
The documentation format of ``.c`` files is also verified by the kernel build
6060
when it is requested to perform extra gcc checks::
@@ -365,7 +365,7 @@ differentiated by whether the macro name is immediately followed by a
365365
left parenthesis ('(') for function-like macros or not followed by one
366366
for object-like macros.
367367

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``.
369369
They may have a parameter list. Object-like macros have do not have a
370370
parameter list.
371371

@@ -596,8 +596,8 @@ from the source file.
596596

597597
The kernel-doc extension is included in the kernel source tree, at
598598
``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.
601601

602602
.. _kernel_doc:
603603

Documentation/kbuild/kbuild.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -180,7 +180,7 @@ architecture.
180180
KDOCFLAGS
181181
---------
182182
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
184184
(currently) apply to documentation builds.
185185

186186
ARCH

Documentation/process/coding-style.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -614,7 +614,7 @@ it.
614614

615615
When commenting the kernel API functions, please use the kernel-doc format.
616616
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
618618
applies to kernel-doc comments all the same. Do not add boilerplate
619619
kernel-doc which simply reiterates what's obvious from the signature
620620
of the function.

Documentation/translations/it_IT/doc-guide/kernel-doc.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@ Al fine di verificare che i commenti siano formattati correttamente, potete
8080
eseguire il programma ``kernel-doc`` con un livello di verbosità alto e senza
8181
che questo produca alcuna documentazione. Per esempio::
8282

83-
scripts/kernel-doc -v -none drivers/foo/bar.c
83+
tools/docs/kernel-doc -v -none drivers/foo/bar.c
8484

8585
Il formato della documentazione è verificato della procedura di generazione
8686
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
378378
immediatamente seguito da una parentesi sinistra ('(') mentre in quelle simili a
379379
oggetti no.
380380

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``.
382382
Possono avere un elenco di parametri. Le macro simili a oggetti non hanno un
383383
elenco di parametri.
384384

@@ -595,7 +595,7 @@ documentazione presenti nel file sorgente (*source*).
595595

596596
L'estensione kernel-doc fa parte dei sorgenti del kernel, la si può trovare
597597
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
599599
dai file sorgenti.
600600

601601
Come utilizzare kernel-doc per generare pagine man
@@ -604,4 +604,4 @@ Come utilizzare kernel-doc per generare pagine man
604604
Se volete utilizzare kernel-doc solo per generare delle pagine man, potete
605605
farlo direttamente dai sorgenti del kernel::
606606

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

Documentation/translations/sp_SP/process/coding-style.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -633,7 +633,7 @@ posiblemente POR QUÉ hace esto.
633633

634634
Al comentar las funciones de la API del kernel, utilice el formato
635635
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.
637637

638638
El estilo preferido para comentarios largos (de varias líneas) es:
639639

Documentation/translations/zh_CN/doc-guide/kernel-doc.rst

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ kernel-doc注释用 ``/**`` 作为开始标记。 ``kernel-doc`` 工具将提取
4343
用详细模式和不生成实际输出来运行 ``kernel-doc`` 工具,可以验证文档注释的格式
4444
是否正确。例如::
4545

46-
scripts/kernel-doc -v -none drivers/foo/bar.c
46+
tools/docs/kernel-doc -v -none drivers/foo/bar.c
4747

4848
当请求执行额外的gcc检查时,内核构建将验证文档格式::
4949

@@ -473,7 +473,7 @@ doc: *title*
473473
如果没有选项,kernel-doc指令将包含源文件中的所有文档注释。
474474

475475
kernel-doc扩展包含在内核源代码树中,位于 ``Documentation/sphinx/kerneldoc.py`` 。
476-
在内部,它使用 ``scripts/kernel-doc`` 脚本从源代码中提取文档注释。
476+
在内部,它使用 ``tools/docs/kernel-doc`` 脚本从源代码中提取文档注释。
477477

478478
.. _kernel_doc_zh:
479479

@@ -482,18 +482,18 @@ kernel-doc扩展包含在内核源代码树中,位于 ``Documentation/sphinx/k
482482

483483
如果您只想使用kernel-doc生成手册页,可以从内核git树这样做::
484484

485-
$ scripts/kernel-doc -man \
485+
$ tools/docs/kernel-doc -man \
486486
$(git grep -l '/\*\*' -- :^Documentation :^tools) \
487487
| scripts/split-man.pl /tmp/man
488488

489489
一些旧版本的git不支持路径排除语法的某些变体。
490490
以下命令之一可能适用于这些版本::
491491

492-
$ scripts/kernel-doc -man \
492+
$ tools/docs/kernel-doc -man \
493493
$(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
494494
| scripts/split-man.pl /tmp/man
495495

496-
$ scripts/kernel-doc -man \
496+
$ tools/docs/kernel-doc -man \
497497
$(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
498498
| scripts/split-man.pl /tmp/man
499499

Documentation/translations/zh_CN/kbuild/kbuild.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -174,7 +174,7 @@ UTS_MACHINE 变量(在某些架构中还包括内核配置)来猜测正确
174174
KDOCFLAGS
175175
---------
176176
指定在构建过程中用于 kernel-doc 检查的额外(警告/错误)标志,查看
177-
scripts/kernel-doc 了解支持的标志。请注意,这目前不适用于文档构建。
177+
tools/docs/kernel-doc 了解支持的标志。请注意,这目前不适用于文档构建。
178178

179179
ARCH
180180
----

Documentation/translations/zh_CN/process/coding-style.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -545,7 +545,7 @@ Linux 里这是提倡的做法,因为这样可以很简单的给读者提供
545545
也可以加上它做这些事情的原因。
546546

547547
当注释内核 API 函数时,请使用 kernel-doc 格式。详见
548-
Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。
548+
Documentation/translations/zh_CN/doc-guide/index.rst 和 tools/docs/kernel-doc 。
549549

550550
长 (多行) 注释的首选风格是:
551551

Documentation/translations/zh_TW/process/coding-style.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -548,7 +548,7 @@ Linux 裏這是提倡的做法,因爲這樣可以很簡單的給讀者提供
548548
也可以加上它做這些事情的原因。
549549

550550
當註釋內核 API 函數時,請使用 kernel-doc 格式。詳見
551-
Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。
551+
Documentation/translations/zh_CN/doc-guide/index.rst 和 tools/docs/kernel-doc 。
552552

553553
長 (多行) 註釋的首選風格是:
554554

0 commit comments

Comments
 (0)