Commit eba6ffd1 authored by Jonathan Corbet's avatar Jonathan Corbet
Browse files

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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
Message-ID: <311d17e403524349940a8b12de6b5e91e554b1f4.1768823489.git.mchehab+huawei@kernel.org>
parent 24f984aa

Documentation/conf.py

+1 −1
Original line number Diff line number Diff line
@@ -585,7 +585,7 @@ pdf_documents = [ 
# 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):

Documentation/doc-guide/kernel-doc.rst

+4 −4
Original line number Diff line number Diff line
@@ -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

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::
@@ -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

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.
@@ -596,8 +596,8 @@ from the source file. 


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:

Documentation/kbuild/kbuild.rst

+1 −1
Original line number Diff line number Diff line
@@ -180,7 +180,7 @@ architecture. 
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

Documentation/process/coding-style.rst

+1 −1
Original line number Diff line number Diff line
@@ -614,7 +614,7 @@ it. 


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.

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

+4 −4
Original line number Diff line number Diff line
@@ -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

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::
@@ -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

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.
@@ -595,7 +595,7 @@ documentazione presenti nel file sorgente (*source*). 


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
@@ -604,4 +604,4 @@ 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