* [PATCH RFC 00/13] Collect documention-related tools under tools/doc
@ 2025-08-13 21:31 Jonathan Corbet
2025-08-13 21:32 ` [PATCH 01/13] docs: Move the "features" tools to tools/doc Jonathan Corbet
` (15 more replies)
0 siblings, 16 replies; 47+ messages in thread
From: Jonathan Corbet @ 2025-08-13 21:31 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa, Randy Dunlap,
Jonathan Corbet
Our documentation-related tools are spread out over various directories;
several are buried in the scripts/ dumping ground. That makes them harder
to discover and harder to maintain.
Recently, the idea of creating a dedicated directory for documentation tools
came up; I decided to see what it would look like. This series creates a
new directory, tools/doc, and moves various utilities there, hopefully
fixing up all of the relevant references in the process.
At the end, rather than move the old, Perl kernel-doc, I simply removed it.
The big elephant lurking in this small room is the home for Python modules;
I left them under scripts/lib, but that is an even less appropriate place
than it was before. I would propose either tools/python or lib/python;
thoughts on that matter welcome.
Jonathan Corbet (13):
docs: Move the "features" tools to tools/doc
docs: move checktransupdate.py to tools/doc
docs: move scripts/check-variable-fonts.sh to tools/doc
docs: move scripts/documentation-file-ref-check to tools/doc
docs: move parallel-wrapper.sh to tools/doc/
docs: move get_abi.py to tools/doc
docs: move sphinx-pre-install to tools/doc
docs: move test_doc_build.py to tools/doc
docs: move parse-headers.pl to tools/doc
docs: move kernel-doc to tools/doc
docs: move split-man.pl to tools/doc
docs: move find-unused-docs.sh to tools/doc
docs: remove kernel-doc.pl
Documentation/Kconfig | 2 +-
Documentation/Makefile | 24 +-
Documentation/conf.py | 2 +-
Documentation/doc-guide/checktransupdate.rst | 6 +-
Documentation/doc-guide/contributing.rst | 2 +-
Documentation/doc-guide/kernel-doc.rst | 18 +-
Documentation/doc-guide/parse-headers.rst | 6 +-
Documentation/doc-guide/sphinx.rst | 6 +-
Documentation/kbuild/kbuild.rst | 2 +-
Documentation/process/coding-style.rst | 2 +-
Documentation/sphinx/kernel_abi.py | 2 +-
Documentation/sphinx/kernel_feat.py | 4 +-
Documentation/sphinx/kerneldoc-preamble.sty | 2 +-
.../it_IT/doc-guide/kernel-doc.rst | 8 +-
.../it_IT/doc-guide/parse-headers.rst | 6 +-
.../translations/it_IT/doc-guide/sphinx.rst | 4 +-
.../sp_SP/process/coding-style.rst | 2 +-
.../zh_CN/doc-guide/checktransupdate.rst | 6 +-
.../zh_CN/doc-guide/contributing.rst | 2 +-
.../zh_CN/doc-guide/kernel-doc.rst | 16 +-
.../zh_CN/doc-guide/parse-headers.rst | 6 +-
.../translations/zh_CN/doc-guide/sphinx.rst | 4 +-
Documentation/translations/zh_CN/how-to.rst | 4 +-
.../translations/zh_CN/kbuild/kbuild.rst | 2 +-
.../zh_CN/process/coding-style.rst | 2 +-
.../zh_TW/process/coding-style.rst | 2 +-
Documentation/userspace-api/media/Makefile | 2 +-
MAINTAINERS | 11 +-
Makefile | 2 +-
drivers/gpu/drm/i915/Makefile | 2 +-
scripts/kernel-doc | 1 -
scripts/kernel-doc.pl | 2439 -----------------
.../doc}/check-variable-fonts.sh | 2 +-
{scripts => tools/doc}/checktransupdate.py | 8 +-
.../doc}/documentation-file-ref-check | 2 +-
.../scripts => tools/doc}/features-refresh.sh | 0
{scripts => tools/doc}/find-unused-docs.sh | 8 +-
{scripts => tools/doc}/get_abi.py | 0
{scripts => tools/doc}/get_feat.pl | 2 +-
scripts/kernel-doc.py => tools/doc/kernel-doc | 0
.../features => tools/doc}/list-arch.sh | 2 +-
.../sphinx => tools/doc}/parallel-wrapper.sh | 0
.../sphinx => tools/doc}/parse-headers.pl | 4 +-
{scripts => tools/doc}/sphinx-pre-install | 2 +-
{scripts => tools/doc}/split-man.pl | 0
{scripts => tools/doc}/test_doc_build.py | 0
46 files changed, 91 insertions(+), 2538 deletions(-)
delete mode 120000 scripts/kernel-doc
delete mode 100755 scripts/kernel-doc.pl
rename {scripts => tools/doc}/check-variable-fonts.sh (98%)
rename {scripts => tools/doc}/checktransupdate.py (98%)
rename {scripts => tools/doc}/documentation-file-ref-check (99%)
rename {Documentation/features/scripts => tools/doc}/features-refresh.sh (100%)
rename {scripts => tools/doc}/find-unused-docs.sh (79%)
rename {scripts => tools/doc}/get_abi.py (100%)
rename {scripts => tools/doc}/get_feat.pl (99%)
rename scripts/kernel-doc.py => tools/doc/kernel-doc (100%)
rename {Documentation/features => tools/doc}/list-arch.sh (83%)
rename {Documentation/sphinx => tools/doc}/parallel-wrapper.sh (100%)
rename {Documentation/sphinx => tools/doc}/parse-headers.pl (98%)
rename {scripts => tools/doc}/sphinx-pre-install (99%)
rename {scripts => tools/doc}/split-man.pl (100%)
rename {scripts => tools/doc}/test_doc_build.py (100%)
--
2.50.1
^ permalink raw reply [flat|nested] 47+ messages in thread
* [PATCH 01/13] docs: Move the "features" tools to tools/doc
2025-08-13 21:31 [PATCH RFC 00/13] Collect documention-related tools under tools/doc Jonathan Corbet
@ 2025-08-13 21:32 ` Jonathan Corbet
2025-08-13 23:38 ` Mauro Carvalho Chehab
2025-08-13 21:32 ` [PATCH 02/13] docs: move checktransupdate.py " Jonathan Corbet
` (14 subsequent siblings)
15 siblings, 1 reply; 47+ messages in thread
From: Jonathan Corbet @ 2025-08-13 21:32 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa, Randy Dunlap,
Jonathan Corbet
The scripts for managing the features docs are found in three different
directories; unite them all under tools/doc and update references as
needed.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
Documentation/sphinx/kernel_feat.py | 4 ++--
.../features/scripts => tools/doc}/features-refresh.sh | 0
{scripts => tools/doc}/get_feat.pl | 2 +-
{Documentation/features => tools/doc}/list-arch.sh | 2 +-
4 files changed, 4 insertions(+), 4 deletions(-)
rename {Documentation/features/scripts => tools/doc}/features-refresh.sh (100%)
rename {scripts => tools/doc}/get_feat.pl (99%)
rename {Documentation/features => tools/doc}/list-arch.sh (83%)
diff --git a/Documentation/sphinx/kernel_feat.py b/Documentation/sphinx/kernel_feat.py
index e3a51867f27b..5453a7b1fc9f 100644
--- a/Documentation/sphinx/kernel_feat.py
+++ b/Documentation/sphinx/kernel_feat.py
@@ -13,7 +13,7 @@
:license: GPL Version 2, June 1991 see Linux/COPYING for details.
The ``kernel-feat`` (:py:class:`KernelFeat`) directive calls the
- scripts/get_feat.pl script to parse the Kernel ABI files.
+ tools/doc/get_feat.pl script to parse the Kernel ABI files.
Overview of directive's argument and options.
@@ -83,7 +83,7 @@ class KernelFeat(Directive):
srctree = os.path.abspath(os.environ["srctree"])
args = [
- os.path.join(srctree, 'scripts/get_feat.pl'),
+ os.path.join(srctree, 'tools/doc/get_feat.pl'),
'rest',
'--enable-fname',
'--dir',
diff --git a/Documentation/features/scripts/features-refresh.sh b/tools/doc/features-refresh.sh
similarity index 100%
rename from Documentation/features/scripts/features-refresh.sh
rename to tools/doc/features-refresh.sh
diff --git a/scripts/get_feat.pl b/tools/doc/get_feat.pl
similarity index 99%
rename from scripts/get_feat.pl
rename to tools/doc/get_feat.pl
index 40fb28c8424e..d75e7c85dc85 100755
--- a/scripts/get_feat.pl
+++ b/tools/doc/get_feat.pl
@@ -18,7 +18,7 @@ my $enable_fname;
my $basename = abs_path($0);
$basename =~ s,/[^/]+$,/,;
-my $prefix=$basename . "../Documentation/features";
+my $prefix=$basename . "../../Documentation/features";
# Used only at for full features output. The script will auto-adjust
# such values for the minimal possible values
diff --git a/Documentation/features/list-arch.sh b/tools/doc/list-arch.sh
similarity index 83%
rename from Documentation/features/list-arch.sh
rename to tools/doc/list-arch.sh
index ac8ff7f6f859..96fe83b7058b 100755
--- a/Documentation/features/list-arch.sh
+++ b/tools/doc/list-arch.sh
@@ -8,4 +8,4 @@
ARCH=${1:-$(uname -m | sed 's/x86_64/x86/' | sed 's/i386/x86/' | sed 's/s390x/s390/')}
-$(dirname $0)/../../scripts/get_feat.pl list --arch $ARCH
+$(dirname $0)/get_feat.pl list --arch $ARCH
--
2.50.1
^ permalink raw reply related [flat|nested] 47+ messages in thread
* [PATCH 02/13] docs: move checktransupdate.py to tools/doc
2025-08-13 21:31 [PATCH RFC 00/13] Collect documention-related tools under tools/doc Jonathan Corbet
2025-08-13 21:32 ` [PATCH 01/13] docs: Move the "features" tools to tools/doc Jonathan Corbet
@ 2025-08-13 21:32 ` Jonathan Corbet
2025-08-13 23:51 ` Mauro Carvalho Chehab
2025-08-13 21:32 ` [PATCH 03/13] docs: move scripts/check-variable-fonts.sh " Jonathan Corbet
` (13 subsequent siblings)
15 siblings, 1 reply; 47+ messages in thread
From: Jonathan Corbet @ 2025-08-13 21:32 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa, Randy Dunlap,
Jonathan Corbet
The checktranslate.py tool currently languishes in scripts/; move it to
tools/doc and update references accordingly.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
Documentation/doc-guide/checktransupdate.rst | 6 +++---
.../translations/zh_CN/doc-guide/checktransupdate.rst | 6 +++---
Documentation/translations/zh_CN/how-to.rst | 2 +-
MAINTAINERS | 2 +-
{scripts => tools/doc}/checktransupdate.py | 8 ++++----
5 files changed, 12 insertions(+), 12 deletions(-)
rename {scripts => tools/doc}/checktransupdate.py (98%)
diff --git a/Documentation/doc-guide/checktransupdate.rst b/Documentation/doc-guide/checktransupdate.rst
index dfaf9d373747..48bf1ee9a62e 100644
--- a/Documentation/doc-guide/checktransupdate.rst
+++ b/Documentation/doc-guide/checktransupdate.rst
@@ -27,15 +27,15 @@ Usage
::
- ./scripts/checktransupdate.py --help
+ tools/doc/checktransupdate.py --help
Please refer to the output of argument parser for usage details.
Samples
-- ``./scripts/checktransupdate.py -l zh_CN``
+- ``tools/doc/checktransupdate.py -l zh_CN``
This will print all the files that need to be updated in the zh_CN locale.
-- ``./scripts/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst``
+- ``tools/doc/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst``
This will only print the status of the specified file.
Then the output is something like:
diff --git a/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst b/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
index d20b4ce66b9f..165e25155084 100644
--- a/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
+++ b/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
@@ -28,15 +28,15 @@
::
- ./scripts/checktransupdate.py --help
+ tools/doc/checktransupdate.py --help
具体用法请参考参数解析器的输出
示例
-- ``./scripts/checktransupdate.py -l zh_CN``
+- ``tools/doc/checktransupdate.py -l zh_CN``
这将打印 zh_CN 语言中需要更新的所有文件。
-- ``./scripts/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst``
+- ``tools/doc/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst``
这将只打印指定文件的状态。
然后输出类似如下的内容：
diff --git a/Documentation/translations/zh_CN/how-to.rst b/Documentation/translations/zh_CN/how-to.rst
index ddd99c0f9b4d..cf66c72ee0c5 100644
--- a/Documentation/translations/zh_CN/how-to.rst
+++ b/Documentation/translations/zh_CN/how-to.rst
@@ -437,7 +437,7 @@ git email 默认会抄送给您一份，所以您可以切换为审阅者的角
对于首次参与 Linux 内核中文文档翻译的新手，建议您在 linux 目录中运行以下命令：
::
- ./script/checktransupdate.py -l zh_CN``
+ tools/doc/checktransupdate.py -l zh_CN``
该命令会列出需要翻译或更新的英文文档，结果同时保存在 checktransupdate.log 中。
diff --git a/MAINTAINERS b/MAINTAINERS
index dafc11712544..a3a396fc1c3f 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7301,8 +7301,8 @@ S: Maintained
P: Documentation/doc-guide/maintainer-profile.rst
T: git git://git.lwn.net/linux.git docs-next
F: Documentation/
+F: tools/doc/
F: scripts/check-variable-fonts.sh
-F: scripts/checktransupdate.py
F: scripts/documentation-file-ref-check
F: scripts/get_abi.py
F: scripts/kernel-doc*
diff --git a/scripts/checktransupdate.py b/tools/doc/checktransupdate.py
similarity index 98%
rename from scripts/checktransupdate.py
rename to tools/doc/checktransupdate.py
index e39529e46c3d..61bd7b02ca55 100755
--- a/scripts/checktransupdate.py
+++ b/tools/doc/checktransupdate.py
@@ -9,9 +9,9 @@ commit to find the latest english commit from the translation commit
differences occur, report the file and commits that need to be updated.
The usage is as follows:
-- ./scripts/checktransupdate.py -l zh_CN
+- tools/doc/checktransupdate.py -l zh_CN
This will print all the files that need to be updated or translated in the zh_CN locale.
-- ./scripts/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst
+- tools/doc/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst
This will only print the status of the specified file.
The output is something like:
@@ -168,7 +168,7 @@ def check_per_file(file_path):
def valid_locales(locale):
"""Check if the locale is valid or not"""
script_path = os.path.dirname(os.path.abspath(__file__))
- linux_path = os.path.join(script_path, "..")
+ linux_path = os.path.join(script_path, "../..")
if not os.path.isdir(f"{linux_path}/Documentation/translations/{locale}"):
raise ArgumentTypeError("Invalid locale: {locale}")
return locale
@@ -232,7 +232,7 @@ def config_logging(log_level, log_file="checktransupdate.log"):
def main():
"""Main function of the script"""
script_path = os.path.dirname(os.path.abspath(__file__))
- linux_path = os.path.join(script_path, "..")
+ linux_path = os.path.join(script_path, "../..")
parser = ArgumentParser(description="Check the translation update")
parser.add_argument(
--
2.50.1
^ permalink raw reply related [flat|nested] 47+ messages in thread
* [PATCH 03/13] docs: move scripts/check-variable-fonts.sh to tools/doc
2025-08-13 21:31 [PATCH RFC 00/13] Collect documention-related tools under tools/doc Jonathan Corbet
2025-08-13 21:32 ` [PATCH 01/13] docs: Move the "features" tools to tools/doc Jonathan Corbet
2025-08-13 21:32 ` [PATCH 02/13] docs: move checktransupdate.py " Jonathan Corbet
@ 2025-08-13 21:32 ` Jonathan Corbet
2025-08-13 23:46 ` Mauro Carvalho Chehab
2025-08-13 21:32 ` [PATCH 04/13] docs: move scripts/documentation-file-ref-check " Jonathan Corbet
` (12 subsequent siblings)
15 siblings, 1 reply; 47+ messages in thread
From: Jonathan Corbet @ 2025-08-13 21:32 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa, Randy Dunlap,
Jonathan Corbet
Move this script to live with the rest of the documentation tools.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
Documentation/Makefile | 2 +-
MAINTAINERS | 1 -
{scripts => tools/doc}/check-variable-fonts.sh | 2 +-
3 files changed, 2 insertions(+), 3 deletions(-)
rename {scripts => tools/doc}/check-variable-fonts.sh (98%)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 820f07e0afe6..70095465dce1 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -146,7 +146,7 @@ pdfdocs: DENY_VF = XDG_CONFIG_HOME=$(FONTS_CONF_DENY_VF)
pdfdocs: latexdocs
@$(srctree)/scripts/sphinx-pre-install --version-check
$(foreach var,$(SPHINXDIRS), \
- $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" $(DENY_VF) -C $(BUILDDIR)/$(var)/latex || sh $(srctree)/scripts/check-variable-fonts.sh || exit; \
+ $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" $(DENY_VF) -C $(BUILDDIR)/$(var)/latex || sh $(srctree)/tools/doc/check-variable-fonts.sh || exit; \
mkdir -p $(BUILDDIR)/$(var)/pdf; \
mv $(subst .tex,.pdf,$(wildcard $(BUILDDIR)/$(var)/latex/*.tex)) $(BUILDDIR)/$(var)/pdf/; \
)
diff --git a/MAINTAINERS b/MAINTAINERS
index a3a396fc1c3f..ca4c7992369d 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7302,7 +7302,6 @@ P: Documentation/doc-guide/maintainer-profile.rst
T: git git://git.lwn.net/linux.git docs-next
F: Documentation/
F: tools/doc/
-F: scripts/check-variable-fonts.sh
F: scripts/documentation-file-ref-check
F: scripts/get_abi.py
F: scripts/kernel-doc*
diff --git a/scripts/check-variable-fonts.sh b/tools/doc/check-variable-fonts.sh
similarity index 98%
rename from scripts/check-variable-fonts.sh
rename to tools/doc/check-variable-fonts.sh
index ce63f0acea5f..9660df53d716 100755
--- a/scripts/check-variable-fonts.sh
+++ b/tools/doc/check-variable-fonts.sh
@@ -106,7 +106,7 @@ if [ "x$notocjkvffonts" != "x" ] ; then
echo 'Or, CJK pages can be skipped by uninstalling texlive-xecjk.'
echo
echo 'For more info on denylisting, other options, and variable font, see header'
- echo 'comments of scripts/check-variable-fonts.sh.'
+ echo 'comments of tools/doc/check-variable-fonts.sh.'
echo '============================================================================='
fi
--
2.50.1
^ permalink raw reply related [flat|nested] 47+ messages in thread
* [PATCH 04/13] docs: move scripts/documentation-file-ref-check to tools/doc
2025-08-13 21:31 [PATCH RFC 00/13] Collect documention-related tools under tools/doc Jonathan Corbet
` (2 preceding siblings ...)
2025-08-13 21:32 ` [PATCH 03/13] docs: move scripts/check-variable-fonts.sh " Jonathan Corbet
@ 2025-08-13 21:32 ` Jonathan Corbet
2025-08-13 23:47 ` Mauro Carvalho Chehab
2025-08-13 21:32 ` [PATCH 05/13] docs: move parallel-wrapper.sh to tools/doc/ Jonathan Corbet
` (11 subsequent siblings)
15 siblings, 1 reply; 47+ messages in thread
From: Jonathan Corbet @ 2025-08-13 21:32 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa, Randy Dunlap,
Jonathan Corbet
Add this script to the growing collection of documentation tools.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
Documentation/Makefile | 4 ++--
MAINTAINERS | 3 +--
scripts/sphinx-pre-install | 2 +-
{scripts => tools/doc}/documentation-file-ref-check | 2 +-
4 files changed, 5 insertions(+), 6 deletions(-)
rename {scripts => tools/doc}/documentation-file-ref-check (99%)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 70095465dce1..f7b8342f9666 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -8,7 +8,7 @@ subdir- := devicetree/bindings
ifneq ($(MAKECMDGOALS),cleandocs)
# Check for broken documentation file references
ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y)
-$(shell $(srctree)/scripts/documentation-file-ref-check --warn)
+$(shell $(srctree)/tools/doc/documentation-file-ref-check --warn)
endif
# Check for broken ABI files
@@ -167,7 +167,7 @@ endif # HAVE_SPHINX
# work or silently pass without Sphinx.
refcheckdocs:
- $(Q)cd $(srctree);scripts/documentation-file-ref-check
+ $(Q)cd $(srctree); tools/doc/documentation-file-ref-check
cleandocs:
$(Q)rm -rf $(BUILDDIR)
diff --git a/MAINTAINERS b/MAINTAINERS
index ca4c7992369d..ec9872642597 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7302,7 +7302,6 @@ P: Documentation/doc-guide/maintainer-profile.rst
T: git git://git.lwn.net/linux.git docs-next
F: Documentation/
F: tools/doc/
-F: scripts/documentation-file-ref-check
F: scripts/get_abi.py
F: scripts/kernel-doc*
F: scripts/lib/abi/*
@@ -7342,7 +7341,7 @@ M: Mauro Carvalho Chehab <mchehab@kernel.org>
L: linux-doc@vger.kernel.org
S: Maintained
F: Documentation/sphinx/parse-headers.pl
-F: scripts/documentation-file-ref-check
+F: tools/doc/
F: scripts/sphinx-pre-install
DOCUMENTATION/ITALIAN
diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index b8474848df4e..5d006a037428 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -406,7 +406,7 @@ class MissingCheckers(AncillaryMethods):
Right now, we still need Perl for doc build, as it is required
by some tools called at docs or kernel build time, like:
- scripts/documentation-file-ref-check
+ tools/doc/documentation-file-ref-check
Also, checkpatch is on Perl.
"""
diff --git a/scripts/documentation-file-ref-check b/tools/doc/documentation-file-ref-check
similarity index 99%
rename from scripts/documentation-file-ref-check
rename to tools/doc/documentation-file-ref-check
index 408b1dbe7884..2dc53f5661b1 100755
--- a/scripts/documentation-file-ref-check
+++ b/tools/doc/documentation-file-ref-check
@@ -17,7 +17,7 @@ my %false_positives = (
);
my $scriptname = $0;
-$scriptname =~ s,.*/([^/]+/),$1,;
+$scriptname =~ s,tools/doc/([^/]+/),$1,;
# Parse arguments
my $help = 0;
--
2.50.1
^ permalink raw reply related [flat|nested] 47+ messages in thread
* [PATCH 05/13] docs: move parallel-wrapper.sh to tools/doc/
2025-08-13 21:31 [PATCH RFC 00/13] Collect documention-related tools under tools/doc Jonathan Corbet
` (3 preceding siblings ...)
2025-08-13 21:32 ` [PATCH 04/13] docs: move scripts/documentation-file-ref-check " Jonathan Corbet
@ 2025-08-13 21:32 ` Jonathan Corbet
2025-08-13 23:31 ` Mauro Carvalho Chehab
2025-08-13 21:32 ` [PATCH 06/13] docs: move get_abi.py to tools/doc Jonathan Corbet
` (10 subsequent siblings)
15 siblings, 1 reply; 47+ messages in thread
From: Jonathan Corbet @ 2025-08-13 21:32 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa, Randy Dunlap,
Jonathan Corbet
This little script was buried in Documentation/sphinx/; put it with the
other documentation-related tools.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
Documentation/Makefile | 2 +-
{Documentation/sphinx => tools/doc}/parallel-wrapper.sh | 0
2 files changed, 1 insertion(+), 1 deletion(-)
rename {Documentation/sphinx => tools/doc}/parallel-wrapper.sh (100%)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index f7b8342f9666..962c4fab94b0 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -91,7 +91,7 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \
BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(src)/$5/$(SPHINX_CONF)) \
$(PYTHON3) $(srctree)/scripts/jobserver-exec \
- $(CONFIG_SHELL) $(srctree)/Documentation/sphinx/parallel-wrapper.sh \
+ $(CONFIG_SHELL) $(srctree)/tools/doc/parallel-wrapper.sh \
$(SPHINXBUILD) \
-b $2 \
-c $(abspath $(src)) \
diff --git a/Documentation/sphinx/parallel-wrapper.sh b/tools/doc/parallel-wrapper.sh
similarity index 100%
rename from Documentation/sphinx/parallel-wrapper.sh
rename to tools/doc/parallel-wrapper.sh
--
2.50.1
^ permalink raw reply related [flat|nested] 47+ messages in thread
* [PATCH 06/13] docs: move get_abi.py to tools/doc
2025-08-13 21:31 [PATCH RFC 00/13] Collect documention-related tools under tools/doc Jonathan Corbet
` (4 preceding siblings ...)
2025-08-13 21:32 ` [PATCH 05/13] docs: move parallel-wrapper.sh to tools/doc/ Jonathan Corbet
@ 2025-08-13 21:32 ` Jonathan Corbet
2025-08-13 23:43 ` Mauro Carvalho Chehab
2025-08-13 21:32 ` [PATCH 07/13] docs: move sphinx-pre-install " Jonathan Corbet
` (9 subsequent siblings)
15 siblings, 1 reply; 47+ messages in thread
From: Jonathan Corbet @ 2025-08-13 21:32 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa, Randy Dunlap,
Jonathan Corbet
Move this tool out of scripts/ to join the other documentation tools; fix
up a couple of erroneous references in the process.
It's worth noting that this script will fail badly unless one has a
PYTHONPATH referencing scripts/lib/abi.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
Documentation/Kconfig | 2 +-
Documentation/Makefile | 2 +-
Documentation/sphinx/kernel_abi.py | 2 +-
MAINTAINERS | 1 -
{scripts => tools/doc}/get_abi.py | 0
5 files changed, 3 insertions(+), 4 deletions(-)
rename {scripts => tools/doc}/get_abi.py (100%)
diff --git a/Documentation/Kconfig b/Documentation/Kconfig
index 3a0e7ac0c4e3..70178e9e0c6c 100644
--- a/Documentation/Kconfig
+++ b/Documentation/Kconfig
@@ -19,7 +19,7 @@ config WARN_ABI_ERRORS
described at Documentation/ABI/README. Yet, as they're manually
written, it would be possible that some of those files would
have errors that would break them for being parsed by
- scripts/get_abi.pl. Add a check to verify them.
+ tools/doc/get_abi.py. Add a check to verify them.
If unsure, select 'N'.
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 962c4fab94b0..eef5decb79b8 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -13,7 +13,7 @@ endif
# Check for broken ABI files
ifeq ($(CONFIG_WARN_ABI_ERRORS),y)
-$(shell $(srctree)/scripts/get_abi.py --dir $(srctree)/Documentation/ABI validate)
+$(shell $(srctree)/tools/doc/get_abi.py --dir $(srctree)/Documentation/ABI validate)
endif
endif
diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
index 4c4375201b9e..32e39fb8bc3b 100644
--- a/Documentation/sphinx/kernel_abi.py
+++ b/Documentation/sphinx/kernel_abi.py
@@ -14,7 +14,7 @@
:license: GPL Version 2, June 1991 see Linux/COPYING for details.
The ``kernel-abi`` (:py:class:`KernelCmd`) directive calls the
- scripts/get_abi.py script to parse the Kernel ABI files.
+ AbiParser class to parse the Kernel ABI files.
Overview of directive's argument and options.
diff --git a/MAINTAINERS b/MAINTAINERS
index ec9872642597..b41b78215035 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7302,7 +7302,6 @@ P: Documentation/doc-guide/maintainer-profile.rst
T: git git://git.lwn.net/linux.git docs-next
F: Documentation/
F: tools/doc/
-F: scripts/get_abi.py
F: scripts/kernel-doc*
F: scripts/lib/abi/*
F: scripts/lib/kdoc/*
diff --git a/scripts/get_abi.py b/tools/doc/get_abi.py
similarity index 100%
rename from scripts/get_abi.py
rename to tools/doc/get_abi.py
--
2.50.1
^ permalink raw reply related [flat|nested] 47+ messages in thread
* [PATCH 07/13] docs: move sphinx-pre-install to tools/doc
2025-08-13 21:31 [PATCH RFC 00/13] Collect documention-related tools under tools/doc Jonathan Corbet
` (5 preceding siblings ...)
2025-08-13 21:32 ` [PATCH 06/13] docs: move get_abi.py to tools/doc Jonathan Corbet
@ 2025-08-13 21:32 ` Jonathan Corbet
2025-08-13 23:36 ` Mauro Carvalho Chehab
2025-08-13 21:32 ` [PATCH 08/13] docs: move test_doc_build.py " Jonathan Corbet
` (8 subsequent siblings)
15 siblings, 1 reply; 47+ messages in thread
From: Jonathan Corbet @ 2025-08-13 21:32 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa, Randy Dunlap,
Jonathan Corbet
Put this tool with the other documentation-related scripts.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
Documentation/Makefile | 14 +++++++-------
Documentation/doc-guide/sphinx.rst | 4 ++--
Documentation/sphinx/kerneldoc-preamble.sty | 2 +-
.../translations/it_IT/doc-guide/sphinx.rst | 4 ++--
.../translations/zh_CN/doc-guide/sphinx.rst | 4 ++--
Documentation/translations/zh_CN/how-to.rst | 2 +-
MAINTAINERS | 2 --
{scripts => tools/doc}/sphinx-pre-install | 0
8 files changed, 15 insertions(+), 17 deletions(-)
rename {scripts => tools/doc}/sphinx-pre-install (100%)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index eef5decb79b8..818d866756b0 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -46,7 +46,7 @@ ifeq ($(HAVE_SPHINX),0)
.DEFAULT:
$(warning The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed and in PATH, or set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable.)
@echo
- @$(srctree)/scripts/sphinx-pre-install
+ @$(srctree)/tools/doc/sphinx-pre-install
@echo " SKIP Sphinx $@ target."
else # HAVE_SPHINX
@@ -105,7 +105,7 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
fi
htmldocs:
- @$(srctree)/scripts/sphinx-pre-install --version-check
+ @$(srctree)/tools/doc/sphinx-pre-install --version-check
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
# If Rust support is available and .config exists, add rustdoc generated contents.
@@ -119,7 +119,7 @@ endif
endif
texinfodocs:
- @$(srctree)/scripts/sphinx-pre-install --version-check
+ @$(srctree)/tools/doc/sphinx-pre-install --version-check
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,texinfo,$(var),texinfo,$(var)))
# Note: the 'info' Make target is generated by sphinx itself when
@@ -131,7 +131,7 @@ linkcheckdocs:
@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
latexdocs:
- @$(srctree)/scripts/sphinx-pre-install --version-check
+ @$(srctree)/tools/doc/sphinx-pre-install --version-check
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))
ifeq ($(HAVE_PDFLATEX),0)
@@ -144,7 +144,7 @@ else # HAVE_PDFLATEX
pdfdocs: DENY_VF = XDG_CONFIG_HOME=$(FONTS_CONF_DENY_VF)
pdfdocs: latexdocs
- @$(srctree)/scripts/sphinx-pre-install --version-check
+ @$(srctree)/tools/doc/sphinx-pre-install --version-check
$(foreach var,$(SPHINXDIRS), \
$(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" $(DENY_VF) -C $(BUILDDIR)/$(var)/latex || sh $(srctree)/tools/doc/check-variable-fonts.sh || exit; \
mkdir -p $(BUILDDIR)/$(var)/pdf; \
@@ -154,11 +154,11 @@ pdfdocs: latexdocs
endif # HAVE_PDFLATEX
epubdocs:
- @$(srctree)/scripts/sphinx-pre-install --version-check
+ @$(srctree)/tools/doc/sphinx-pre-install --version-check
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))
xmldocs:
- @$(srctree)/scripts/sphinx-pre-install --version-check
+ @$(srctree)/tools/doc/sphinx-pre-install --version-check
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var)))
endif # HAVE_SPHINX
diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index 607589592bfb..2a0fc6c39cf4 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -106,7 +106,7 @@ There's a script that automatically checks for Sphinx dependencies. If it can
recognize your distribution, it will also give a hint about the install
command line options for your distro::
- $ ./scripts/sphinx-pre-install
+ $ ./tools/doc/sphinx-pre-install
Checking if the needed tools for Fedora release 26 (Twenty Six) are available
Warning: better to also install "texlive-luatex85".
You should run:
@@ -116,7 +116,7 @@ command line options for your distro::
. sphinx_2.4.4/bin/activate
pip install -r Documentation/sphinx/requirements.txt
- Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
+ Can't build as 1 mandatory dependency is missing at ./tools/doc/sphinx-pre-install line 468.
By default, it checks all the requirements for both html and PDF, including
the requirements for images, math expressions and LaTeX build, and assumes
diff --git a/Documentation/sphinx/kerneldoc-preamble.sty b/Documentation/sphinx/kerneldoc-preamble.sty
index 5d68395539fe..736c2568377e 100644
--- a/Documentation/sphinx/kerneldoc-preamble.sty
+++ b/Documentation/sphinx/kerneldoc-preamble.sty
@@ -220,7 +220,7 @@
If you want them, please install non-variable ``Noto Sans CJK''
font families along with the texlive-xecjk package by following
instructions from
- \sphinxcode{./scripts/sphinx-pre-install}.
+ \sphinxcode{./tools/doc/sphinx-pre-install}.
Having optional non-variable ``Noto Serif CJK'' font families will
improve the looks of those translations.
\end{sphinxadmonition}}
diff --git a/Documentation/translations/it_IT/doc-guide/sphinx.rst b/Documentation/translations/it_IT/doc-guide/sphinx.rst
index 1f513bc33618..104aa159c1ce 100644
--- a/Documentation/translations/it_IT/doc-guide/sphinx.rst
+++ b/Documentation/translations/it_IT/doc-guide/sphinx.rst
@@ -109,7 +109,7 @@ Sphinx. Se lo script riesce a riconoscere la vostra distribuzione, allora
sarà in grado di darvi dei suggerimenti su come procedere per completare
l'installazione::
- $ ./scripts/sphinx-pre-install
+ $ ./tools/doc/sphinx-pre-install
Checking if the needed tools for Fedora release 26 (Twenty Six) are available
Warning: better to also install "texlive-luatex85".
You should run:
@@ -119,7 +119,7 @@ l'installazione::
. sphinx_2.4.4/bin/activate
pip install -r Documentation/sphinx/requirements.txt
- Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
+ Can't build as 1 mandatory dependency is missing at ./tools/doc/sphinx-pre-install line 468.
L'impostazione predefinita prevede il controllo dei requisiti per la generazione
di documenti html e PDF, includendo anche il supporto per le immagini, le
diff --git a/Documentation/translations/zh_CN/doc-guide/sphinx.rst b/Documentation/translations/zh_CN/doc-guide/sphinx.rst
index 23eac67fbc30..3d2c4e262bb5 100644
--- a/Documentation/translations/zh_CN/doc-guide/sphinx.rst
+++ b/Documentation/translations/zh_CN/doc-guide/sphinx.rst
@@ -84,7 +84,7 @@ PDF和LaTeX构建
这有一个脚本可以自动检查Sphinx依赖项。如果它认得您的发行版，还会提示您所用发行
版的安装命令::
- $ ./scripts/sphinx-pre-install
+ $ ./tools/doc/sphinx-pre-install
Checking if the needed tools for Fedora release 26 (Twenty Six) are available
Warning: better to also install "texlive-luatex85".
You should run:
@@ -94,7 +94,7 @@ PDF和LaTeX构建
. sphinx_2.4.4/bin/activate
pip install -r Documentation/sphinx/requirements.txt
- Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
+ Can't build as 1 mandatory dependency is missing at ./tools/doc/sphinx-pre-install line 468.
默认情况下，它会检查html和PDF的所有依赖项，包括图像、数学表达式和LaTeX构建的
需求，并假设将使用虚拟Python环境。html构建所需的依赖项被认为是必需的，其他依
diff --git a/Documentation/translations/zh_CN/how-to.rst b/Documentation/translations/zh_CN/how-to.rst
index cf66c72ee0c5..77da507d29cf 100644
--- a/Documentation/translations/zh_CN/how-to.rst
+++ b/Documentation/translations/zh_CN/how-to.rst
@@ -64,7 +64,7 @@ Linux 发行版和简单地使用 Linux 命令行，那么可以迅速开始了
::
cd linux
- ./scripts/sphinx-pre-install
+ ./tools/doc/sphinx-pre-install
以 Fedora 为例，它的输出是这样的::
diff --git a/MAINTAINERS b/MAINTAINERS
index b41b78215035..2f1374130240 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7306,7 +7306,6 @@ F: scripts/kernel-doc*
F: scripts/lib/abi/*
F: scripts/lib/kdoc/*
F: tools/net/ynl/pyynl/lib/doc_generator.py
-F: scripts/sphinx-pre-install
X: Documentation/ABI/
X: Documentation/admin-guide/media/
X: Documentation/devicetree/
@@ -7341,7 +7340,6 @@ L: linux-doc@vger.kernel.org
S: Maintained
F: Documentation/sphinx/parse-headers.pl
F: tools/doc/
-F: scripts/sphinx-pre-install
DOCUMENTATION/ITALIAN
M: Federico Vaga <federico.vaga@vaga.pv.it>
diff --git a/scripts/sphinx-pre-install b/tools/doc/sphinx-pre-install
similarity index 100%
rename from scripts/sphinx-pre-install
rename to tools/doc/sphinx-pre-install
--
2.50.1
^ permalink raw reply related [flat|nested] 47+ messages in thread
* [PATCH 08/13] docs: move test_doc_build.py to tools/doc
2025-08-13 21:31 [PATCH RFC 00/13] Collect documention-related tools under tools/doc Jonathan Corbet
` (6 preceding siblings ...)
2025-08-13 21:32 ` [PATCH 07/13] docs: move sphinx-pre-install " Jonathan Corbet
@ 2025-08-13 21:32 ` Jonathan Corbet
2025-08-13 23:36 ` Mauro Carvalho Chehab
2025-08-13 21:32 ` [PATCH 09/13] docs: move parse-headers.pl " Jonathan Corbet
` (7 subsequent siblings)
15 siblings, 1 reply; 47+ messages in thread
From: Jonathan Corbet @ 2025-08-13 21:32 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa, Randy Dunlap,
Jonathan Corbet
Add this tool to tools/doc.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
Documentation/doc-guide/sphinx.rst | 2 +-
{scripts => tools/doc}/test_doc_build.py | 0
2 files changed, 1 insertion(+), 1 deletion(-)
rename {scripts => tools/doc}/test_doc_build.py (100%)
diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index 2a0fc6c39cf4..d874dd0ed7d0 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -149,7 +149,7 @@ a venv with it with, and install minimal requirements with::
A more comprehensive test can be done by using:
- scripts/test_doc_build.py
+ tools/doc/test_doc_build.py
Such script create one Python venv per supported version,
optionally building documentation for a range of Sphinx versions.
diff --git a/scripts/test_doc_build.py b/tools/doc/test_doc_build.py
similarity index 100%
rename from scripts/test_doc_build.py
rename to tools/doc/test_doc_build.py
--
2.50.1
^ permalink raw reply related [flat|nested] 47+ messages in thread
* [PATCH 09/13] docs: move parse-headers.pl to tools/doc
2025-08-13 21:31 [PATCH RFC 00/13] Collect documention-related tools under tools/doc Jonathan Corbet
` (7 preceding siblings ...)
2025-08-13 21:32 ` [PATCH 08/13] docs: move test_doc_build.py " Jonathan Corbet
@ 2025-08-13 21:32 ` Jonathan Corbet
2025-08-13 23:32 ` Mauro Carvalho Chehab
2025-08-13 21:32 ` [PATCH 10/13] docs: move kernel-doc " Jonathan Corbet
` (6 subsequent siblings)
15 siblings, 1 reply; 47+ messages in thread
From: Jonathan Corbet @ 2025-08-13 21:32 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa, Randy Dunlap,
Jonathan Corbet
Move the tool and fix all the references, including the numerous ones that
said "parse_headers" instead of "parse-headers".
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
| 6 +++---
| 6 +++---
| 6 +++---
Documentation/userspace-api/media/Makefile | 2 +-
MAINTAINERS | 1 -
| 4 ++--
6 files changed, 12 insertions(+), 13 deletions(-)
rename {Documentation/sphinx => tools/doc}/parse-headers.pl (98%)
--git a/Documentation/doc-guide/parse-headers.rst b/Documentation/doc-guide/parse-headers.rst
index 204b025f1349..954cd81523a0 100644
--- a/Documentation/doc-guide/parse-headers.rst
+++ b/Documentation/doc-guide/parse-headers.rst
@@ -15,14 +15,14 @@ about how to use it inside the Kernel tree.
.. _parse_headers:
-parse_headers.pl
+parse-headers.pl
^^^^^^^^^^^^^^^^
NAME
****
-parse_headers.pl - parse a C file, in order to identify functions, structs,
+parse-headers.pl - parse a C file, in order to identify functions, structs,
enums and defines and create cross-references to a Sphinx book.
@@ -30,7 +30,7 @@ SYNOPSIS
********
-\ **parse_headers.pl**\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
+\ **parse-headers.pl**\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
Where <options> can be: --debug, --help or --usage.
--git a/Documentation/translations/it_IT/doc-guide/parse-headers.rst b/Documentation/translations/it_IT/doc-guide/parse-headers.rst
index 026a23e49767..45b6b6fc4fb5 100644
--- a/Documentation/translations/it_IT/doc-guide/parse-headers.rst
+++ b/Documentation/translations/it_IT/doc-guide/parse-headers.rst
@@ -20,21 +20,21 @@ consultate ``Documentation/userspace-api/media/Makefile``.
.. _it_parse_headers:
-parse_headers.pl
+parse-headers.pl
^^^^^^^^^^^^^^^^
NOME
****
-parse_headers.pl - analizza i file C al fine di identificare funzioni,
+parse-headers.pl - analizza i file C al fine di identificare funzioni,
strutture, enumerati e definizioni, e creare riferimenti per Sphinx
SINTASSI
********
-\ **parse_headers.pl**\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
+\ **parse-headers.pl**\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
Dove <options> può essere: --debug, --usage o --help.
--git a/Documentation/translations/zh_CN/doc-guide/parse-headers.rst b/Documentation/translations/zh_CN/doc-guide/parse-headers.rst
index a08819e904ed..22253fea5da1 100644
--- a/Documentation/translations/zh_CN/doc-guide/parse-headers.rst
+++ b/Documentation/translations/zh_CN/doc-guide/parse-headers.rst
@@ -19,14 +19,14 @@ Sphinx将生成警告。这有助于保持用户空间API文档与内核更改
.. _parse_headers_zh:
-parse_headers.pl
+parse-headers.pl
----------------
脚本名称
~~~~~~~~
-parse_headers.pl——解析一个C文件，识别函数、结构体、枚举、定义并对Sphinx文档
+parse-headers.pl——解析一个C文件，识别函数、结构体、枚举、定义并对Sphinx文档
创建交叉引用。
@@ -34,7 +34,7 @@ parse_headers.pl——解析一个C文件，识别函数、结构体、枚举、
~~~~~~~~
-\ **parse_headers.pl**\ [<选项>] <C文件> <输出文件> [<例外文件>]
+\ **parse-headers.pl**\ [<选项>] <C文件> <输出文件> [<例外文件>]
<选项> 可以是： --debug, --help 或 --usage 。
diff --git a/Documentation/userspace-api/media/Makefile b/Documentation/userspace-api/media/Makefile
index 3d8aaf5c253b..632798bca615 100644
--- a/Documentation/userspace-api/media/Makefile
+++ b/Documentation/userspace-api/media/Makefile
@@ -3,7 +3,7 @@
# Rules to convert a .h file to inline RST documentation
SRC_DIR=$(srctree)/Documentation/userspace-api/media
-PARSER = $(srctree)/Documentation/sphinx/parse-headers.pl
+PARSER = $(srctree)/tools/doc/parse-headers.pl
UAPI = $(srctree)/include/uapi/linux
KAPI = $(srctree)/include/linux
diff --git a/MAINTAINERS b/MAINTAINERS
index 2f1374130240..c2d2ce92bf79 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7338,7 +7338,6 @@ DOCUMENTATION SCRIPTS
M: Mauro Carvalho Chehab <mchehab@kernel.org>
L: linux-doc@vger.kernel.org
S: Maintained
-F: Documentation/sphinx/parse-headers.pl
F: tools/doc/
DOCUMENTATION/ITALIAN
--git a/Documentation/sphinx/parse-headers.pl b/tools/doc/parse-headers.pl
similarity index 98%
rename from Documentation/sphinx/parse-headers.pl
rename to tools/doc/parse-headers.pl
index 7b1458544e2e..47b90bf8c96d 100755
--- a/Documentation/sphinx/parse-headers.pl
+++ b/tools/doc/parse-headers.pl
@@ -340,12 +340,12 @@ __END__
=head1 NAME
-parse_headers.pl - parse a C file, in order to identify functions, structs,
+parse-headers.pl - parse a C file, in order to identify functions, structs,
enums and defines and create cross-references to a Sphinx book.
=head1 SYNOPSIS
-B<parse_headers.pl> [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
+B<parse-headers.pl> [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
Where <options> can be: --debug, --help or --usage.
--
2.50.1
^ permalink raw reply related [flat|nested] 47+ messages in thread
* [PATCH 10/13] docs: move kernel-doc to tools/doc
2025-08-13 21:31 [PATCH RFC 00/13] Collect documention-related tools under tools/doc Jonathan Corbet
` (8 preceding siblings ...)
2025-08-13 21:32 ` [PATCH 09/13] docs: move parse-headers.pl " Jonathan Corbet
@ 2025-08-13 21:32 ` Jonathan Corbet
2025-08-13 23:33 ` Mauro Carvalho Chehab
` (2 more replies)
2025-08-13 21:32 ` [PATCH 11/13] docs: move split-man.pl " Jonathan Corbet
` (5 subsequent siblings)
15 siblings, 3 replies; 47+ messages in thread
From: Jonathan Corbet @ 2025-08-13 21:32 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa, Randy Dunlap,
Jonathan Corbet
Move kernel-doc to join the rest of the tools, and update references
throughout the tree.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
Documentation/conf.py | 2 +-
Documentation/doc-guide/kernel-doc.rst | 12 ++++++------
Documentation/kbuild/kbuild.rst | 2 +-
Documentation/process/coding-style.rst | 2 +-
.../translations/it_IT/doc-guide/kernel-doc.rst | 8 ++++----
.../translations/sp_SP/process/coding-style.rst | 2 +-
.../translations/zh_CN/doc-guide/kernel-doc.rst | 10 +++++-----
Documentation/translations/zh_CN/kbuild/kbuild.rst | 2 +-
.../translations/zh_CN/process/coding-style.rst | 2 +-
.../translations/zh_TW/process/coding-style.rst | 2 +-
MAINTAINERS | 1 -
Makefile | 2 +-
drivers/gpu/drm/i915/Makefile | 2 +-
scripts/find-unused-docs.sh | 2 +-
scripts/kernel-doc | 1 -
scripts/kernel-doc.py => tools/doc/kernel-doc | 0
16 files changed, 25 insertions(+), 27 deletions(-)
delete mode 120000 scripts/kernel-doc
rename scripts/kernel-doc.py => tools/doc/kernel-doc (100%)
diff --git a/Documentation/conf.py b/Documentation/conf.py
index f9828f3862f9..600cf5d32af8 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -564,7 +564,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/doc/kernel-doc.py"
kerneldoc_srctree = ".."
# ------------------------------------------------------------------------------
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index af9697e60165..6fc89d444ada 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -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/doc/kernel-doc -v -none drivers/foo/bar.c
The documentation format is verified by the kernel build when it is
requested to perform extra gcc checks::
@@ -349,7 +349,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/doc/kernel-doc``.
They may have a parameter list. Object-like macros have do not have a
parameter list.
@@ -571,7 +571,7 @@ 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
+``tools/doc/kernel-doc`` script to extract the documentation comments from the
source.
.. _kernel_doc:
@@ -582,17 +582,17 @@ How to use kernel-doc to generate man pages
If you just want to use kernel-doc to generate man pages you can do this
from the kernel git tree::
- $ scripts/kernel-doc -man \
+ $ tools/doc/kernel-doc -man \
$(git grep -l '/\*\*' -- :^Documentation :^tools) \
| scripts/split-man.pl /tmp/man
Some older versions of git do not support some of the variants of syntax for
path exclusion. One of the following commands may work for those versions::
- $ scripts/kernel-doc -man \
+ $ tools/doc/kernel-doc -man \
$(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
| scripts/split-man.pl /tmp/man
- $ scripts/kernel-doc -man \
+ $ tools/doc/kernel-doc -man \
$(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
| scripts/split-man.pl /tmp/man
diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst
index 3388a10f2dcc..ae7b0669e3ec 100644
--- a/Documentation/kbuild/kbuild.rst
+++ b/Documentation/kbuild/kbuild.rst
@@ -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/doc/kernel-doc for which flags are supported. Note that this doesn't
(currently) apply to documentation builds.
ARCH
diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index d1a8e5465ed9..b2d16449a27b 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -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/doc/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.
diff --git a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
index aa0e31d353d6..05ea0f03c80b 100644
--- a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
+++ b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
@@ -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/doc/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/doc/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/doc/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/doc/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man
diff --git a/Documentation/translations/sp_SP/process/coding-style.rst b/Documentation/translations/sp_SP/process/coding-style.rst
index 025223be9706..73c43b49480f 100644
--- a/Documentation/translations/sp_SP/process/coding-style.rst
+++ b/Documentation/translations/sp_SP/process/coding-style.rst
@@ -633,7 +633,7 @@ posiblemente POR QUÉ hace esto.
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/doc/kernel-doc`` para más detalles.
El estilo preferido para comentarios largos (de varias líneas) es:
diff --git a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
index ccfb9b8329c2..b242e52f911c 100644
--- a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
+++ b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
@@ -43,7 +43,7 @@ kernel-doc注释用 ``/**`` 作为开始标记。 ``kernel-doc`` 工具将提取
用详细模式和不生成实际输出来运行 ``kernel-doc`` 工具，可以验证文档注释的格式
是否正确。例如::
- scripts/kernel-doc -v -none drivers/foo/bar.c
+ tools/doc/kernel-doc -v -none drivers/foo/bar.c
当请求执行额外的gcc检查时，内核构建将验证文档格式::
@@ -473,7 +473,7 @@ doc: *title*
如果没有选项，kernel-doc指令将包含源文件中的所有文档注释。
kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/kerneldoc.py`` 。
-在内部，它使用 ``scripts/kernel-doc`` 脚本从源代码中提取文档注释。
+在内部，它使用 ``tools/doc/kernel-doc`` 脚本从源代码中提取文档注释。
.. _kernel_doc_zh:
@@ -482,18 +482,18 @@ kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/k
如果您只想使用kernel-doc生成手册页，可以从内核git树这样做::
- $ scripts/kernel-doc -man \
+ $ tools/doc/kernel-doc -man \
$(git grep -l '/\*\*' -- :^Documentation :^tools) \
| scripts/split-man.pl /tmp/man
一些旧版本的git不支持路径排除语法的某些变体。
以下命令之一可能适用于这些版本::
- $ scripts/kernel-doc -man \
+ $ tools/doc/kernel-doc -man \
$(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
| scripts/split-man.pl /tmp/man
- $ scripts/kernel-doc -man \
+ $ tools/doc/kernel-doc -man \
$(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
| scripts/split-man.pl /tmp/man
diff --git a/Documentation/translations/zh_CN/kbuild/kbuild.rst b/Documentation/translations/zh_CN/kbuild/kbuild.rst
index e5e2aebe1ebc..3650a48a8db6 100644
--- a/Documentation/translations/zh_CN/kbuild/kbuild.rst
+++ b/Documentation/translations/zh_CN/kbuild/kbuild.rst
@@ -158,7 +158,7 @@ UTS_MACHINE 变量（在某些架构中还包括内核配置）来猜测正确
KDOCFLAGS
---------
指定在构建过程中用于 kernel-doc 检查的额外（警告/错误）标志，查看
-scripts/kernel-doc 了解支持的标志。请注意，这目前不适用于文档构建。
+tools/doc/kernel-doc 了解支持的标志。请注意，这目前不适用于文档构建。
ARCH
----
diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst
index 0484d0c65c25..64f0c13ff831 100644
--- a/Documentation/translations/zh_CN/process/coding-style.rst
+++ b/Documentation/translations/zh_CN/process/coding-style.rst
@@ -545,7 +545,7 @@ Linux 里这是提倡的做法，因为这样可以很简单的给读者提供
也可以加上它做这些事情的原因。
当注释内核 API 函数时，请使用 kernel-doc 格式。详见
-Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。
+Documentation/translations/zh_CN/doc-guide/index.rst 和 tools/doc/kernel-doc 。
长 (多行) 注释的首选风格是：
diff --git a/Documentation/translations/zh_TW/process/coding-style.rst b/Documentation/translations/zh_TW/process/coding-style.rst
index 311c6f6bad0b..1e9dee6bbdd0 100644
--- a/Documentation/translations/zh_TW/process/coding-style.rst
+++ b/Documentation/translations/zh_TW/process/coding-style.rst
@@ -548,7 +548,7 @@ Linux 裏這是提倡的做法，因爲這樣可以很簡單的給讀者提供
也可以加上它做這些事情的原因。
當註釋內核 API 函數時，請使用 kernel-doc 格式。詳見
-Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。
+Documentation/translations/zh_CN/doc-guide/index.rst 和 tools/doc/kernel-doc 。
長 (多行) 註釋的首選風格是：
diff --git a/MAINTAINERS b/MAINTAINERS
index c2d2ce92bf79..0fa427577f15 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7302,7 +7302,6 @@ P: Documentation/doc-guide/maintainer-profile.rst
T: git git://git.lwn.net/linux.git docs-next
F: Documentation/
F: tools/doc/
-F: scripts/kernel-doc*
F: scripts/lib/abi/*
F: scripts/lib/kdoc/*
F: tools/net/ynl/pyynl/lib/doc_generator.py
diff --git a/Makefile b/Makefile
index 6bfe776bf3c5..44577bd357bb 100644
--- a/Makefile
+++ b/Makefile
@@ -460,7 +460,7 @@ HOSTPKG_CONFIG = pkg-config
# 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/doc/kernel-doc.py
export KERNELDOC
KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \
diff --git a/drivers/gpu/drm/i915/Makefile b/drivers/gpu/drm/i915/Makefile
index 853543443072..6e732e0079c1 100644
--- a/drivers/gpu/drm/i915/Makefile
+++ b/drivers/gpu/drm/i915/Makefile
@@ -426,7 +426,7 @@ always-$(CONFIG_DRM_I915_WERROR) += \
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 $@
+ $(srctree)/tools/doc/kernel-doc -none -Werror $<; touch $@
$(obj)/%.hdrtest: $(src)/%.h FORCE
$(call if_changed_dep,hdrtest)
diff --git a/scripts/find-unused-docs.sh b/scripts/find-unused-docs.sh
index d6d397fbf917..0ae445dec2e4 100755
--- a/scripts/find-unused-docs.sh
+++ b/scripts/find-unused-docs.sh
@@ -54,7 +54,7 @@ for file in `find $1 -name '*.c'`; do
if [[ ${FILES_INCLUDED[$file]+_} ]]; then
continue;
fi
- str=$(PYTHONDONTWRITEBYTECODE=1 scripts/kernel-doc -export "$file" 2>/dev/null)
+ str=$(PYTHONDONTWRITEBYTECODE=1 tools/doc/kernel-doc -export "$file" 2>/dev/null)
if [[ -n "$str" ]]; then
echo "$file"
fi
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
deleted file mode 120000
index 3b6ef807791a..000000000000
--- a/scripts/kernel-doc
+++ /dev/null
@@ -1 +0,0 @@
-kernel-doc.py
\ No newline at end of file
diff --git a/scripts/kernel-doc.py b/tools/doc/kernel-doc
similarity index 100%
rename from scripts/kernel-doc.py
rename to tools/doc/kernel-doc
--
2.50.1
^ permalink raw reply related [flat|nested] 47+ messages in thread
* [PATCH 11/13] docs: move split-man.pl to tools/doc
2025-08-13 21:31 [PATCH RFC 00/13] Collect documention-related tools under tools/doc Jonathan Corbet
` (9 preceding siblings ...)
2025-08-13 21:32 ` [PATCH 10/13] docs: move kernel-doc " Jonathan Corbet
@ 2025-08-13 21:32 ` Jonathan Corbet
2025-08-13 23:50 ` Mauro Carvalho Chehab
2025-08-13 21:32 ` [PATCH 12/13] docs: move find-unused-docs.sh " Jonathan Corbet
` (4 subsequent siblings)
15 siblings, 1 reply; 47+ messages in thread
From: Jonathan Corbet @ 2025-08-13 21:32 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa, Randy Dunlap,
Jonathan Corbet
...and update all references to it.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
Documentation/doc-guide/kernel-doc.rst | 6 +++---
Documentation/translations/it_IT/doc-guide/kernel-doc.rst | 2 +-
Documentation/translations/zh_CN/doc-guide/kernel-doc.rst | 6 +++---
{scripts => tools/doc}/split-man.pl | 0
4 files changed, 7 insertions(+), 7 deletions(-)
rename {scripts => tools/doc}/split-man.pl (100%)
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 6fc89d444ada..b7c8ce55323c 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -584,15 +584,15 @@ from the kernel git tree::
$ tools/doc/kernel-doc -man \
$(git grep -l '/\*\*' -- :^Documentation :^tools) \
- | scripts/split-man.pl /tmp/man
+ | tools/doc/split-man.pl /tmp/man
Some older versions of git do not support some of the variants of syntax for
path exclusion. One of the following commands may work for those versions::
$ tools/doc/kernel-doc -man \
$(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
- | scripts/split-man.pl /tmp/man
+ | tools/doc/split-man.pl /tmp/man
$ tools/doc/kernel-doc -man \
$(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
- | scripts/split-man.pl /tmp/man
+ | tools/doc/split-man.pl /tmp/man
diff --git a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
index 05ea0f03c80b..bf04ceea2d83 100644
--- a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
+++ b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
@@ -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::
- $ tools/doc/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man
+ $ tools/doc/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | tools/doc/split-man.pl /tmp/man
diff --git a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
index b242e52f911c..a807295bc403 100644
--- a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
+++ b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
@@ -484,16 +484,16 @@ kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/k
$ tools/doc/kernel-doc -man \
$(git grep -l '/\*\*' -- :^Documentation :^tools) \
- | scripts/split-man.pl /tmp/man
+ | tools/doc/split-man.pl /tmp/man
一些旧版本的git不支持路径排除语法的某些变体。
以下命令之一可能适用于这些版本::
$ tools/doc/kernel-doc -man \
$(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
- | scripts/split-man.pl /tmp/man
+ | tools/doc/split-man.pl /tmp/man
$ tools/doc/kernel-doc -man \
$(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
- | scripts/split-man.pl /tmp/man
+ | tools/doc/split-man.pl /tmp/man
diff --git a/scripts/split-man.pl b/tools/doc/split-man.pl
similarity index 100%
rename from scripts/split-man.pl
rename to tools/doc/split-man.pl
--
2.50.1
^ permalink raw reply related [flat|nested] 47+ messages in thread
* [PATCH 12/13] docs: move find-unused-docs.sh to tools/doc
2025-08-13 21:31 [PATCH RFC 00/13] Collect documention-related tools under tools/doc Jonathan Corbet
` (10 preceding siblings ...)
2025-08-13 21:32 ` [PATCH 11/13] docs: move split-man.pl " Jonathan Corbet
@ 2025-08-13 21:32 ` Jonathan Corbet
2025-08-13 23:50 ` Mauro Carvalho Chehab
2025-08-13 21:32 ` [PATCH 13/13] docs: remove kernel-doc.pl Jonathan Corbet
` (3 subsequent siblings)
15 siblings, 1 reply; 47+ messages in thread
From: Jonathan Corbet @ 2025-08-13 21:32 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa, Randy Dunlap,
Jonathan Corbet
...and update references accordingly.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
Documentation/doc-guide/contributing.rst | 2 +-
Documentation/translations/zh_CN/doc-guide/contributing.rst | 2 +-
{scripts => tools/doc}/find-unused-docs.sh | 6 +++---
3 files changed, 5 insertions(+), 5 deletions(-)
rename {scripts => tools/doc}/find-unused-docs.sh (85%)
diff --git a/Documentation/doc-guide/contributing.rst b/Documentation/doc-guide/contributing.rst
index 662c7a840cd5..81633c6c6c11 100644
--- a/Documentation/doc-guide/contributing.rst
+++ b/Documentation/doc-guide/contributing.rst
@@ -152,7 +152,7 @@ generate links to that documentation. Adding ``kernel-doc`` directives to
the documentation to bring those comments in can help the community derive
the full value of the work that has gone into creating them.
-The ``scripts/find-unused-docs.sh`` tool can be used to find these
+The ``tools/doc/find-unused-docs.sh`` tool can be used to find these
overlooked comments.
Note that the most value comes from pulling in the documentation for
diff --git a/Documentation/translations/zh_CN/doc-guide/contributing.rst b/Documentation/translations/zh_CN/doc-guide/contributing.rst
index 394a13b438b0..d205f8ed9fce 100644
--- a/Documentation/translations/zh_CN/doc-guide/contributing.rst
+++ b/Documentation/translations/zh_CN/doc-guide/contributing.rst
@@ -124,7 +124,7 @@ C代码编译器发出的警告常常会被视为误报，从而导致出现了
这使得这些信息更难找到，例如使Sphinx无法生成指向该文档的链接。将 ``kernel-doc``
指令添加到文档中以引入这些注释可以帮助社区获得为编写注释所做工作的全部价值。
-``scripts/find-unused-docs.sh`` 工具可以用来找到这些被忽略的评论。
+``tools/doc/find-unused-docs.sh`` 工具可以用来找到这些被忽略的评论。
请注意，将导出的函数和数据结构引入文档是最有价值的。许多子系统还具有供内部
使用的kernel-doc注释；除非这些注释放在专门针对相关子系统开发人员的文档中，
diff --git a/scripts/find-unused-docs.sh b/tools/doc/find-unused-docs.sh
similarity index 85%
rename from scripts/find-unused-docs.sh
rename to tools/doc/find-unused-docs.sh
index 0ae445dec2e4..a64389a15f09 100755
--- a/scripts/find-unused-docs.sh
+++ b/tools/doc/find-unused-docs.sh
@@ -5,10 +5,10 @@
# This script detects files with kernel-doc comments for exported functions
# that are not included in documentation.
#
-# usage: Run 'scripts/find-unused-docs.sh directory' from top level of kernel
+# usage: Run 'tools/doc/find-unused-docs.sh directory' from top level of kernel
# tree.
#
-# example: $scripts/find-unused-docs.sh drivers/scsi
+# example: $tools/doc/find-unused-docs.sh drivers/scsi
#
# Licensed under the terms of the GNU GPL License
@@ -18,7 +18,7 @@ if ! [ -d "Documentation" ]; then
fi
if [ "$#" -ne 1 ]; then
- echo "Usage: scripts/find-unused-docs.sh directory"
+ echo "Usage: tools/doc/find-unused-docs.sh directory"
exit 1
fi
--
2.50.1
^ permalink raw reply related [flat|nested] 47+ messages in thread
* [PATCH 13/13] docs: remove kernel-doc.pl
2025-08-13 21:31 [PATCH RFC 00/13] Collect documention-related tools under tools/doc Jonathan Corbet
` (11 preceding siblings ...)
2025-08-13 21:32 ` [PATCH 12/13] docs: move find-unused-docs.sh " Jonathan Corbet
@ 2025-08-13 21:32 ` Jonathan Corbet
2025-08-13 23:33 ` Mauro Carvalho Chehab
2025-08-15 2:43 ` Randy Dunlap
2025-08-13 21:38 ` [PATCH RFC 00/13] Collect documention-related tools under tools/doc Jonathan Corbet
` (2 subsequent siblings)
15 siblings, 2 replies; 47+ messages in thread
From: Jonathan Corbet @ 2025-08-13 21:32 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa, Randy Dunlap,
Jonathan Corbet
We've been using the Python version and nobody has missed this one. All
credit goes to Mauro Carvalho Chehab for creating the replacement.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
scripts/kernel-doc.pl | 2439 -----------------------------------------
1 file changed, 2439 deletions(-)
delete mode 100755 scripts/kernel-doc.pl
diff --git a/scripts/kernel-doc.pl b/scripts/kernel-doc.pl
deleted file mode 100755
index 5db23cbf4eb2..000000000000
--- a/scripts/kernel-doc.pl
+++ /dev/null
@@ -1,2439 +0,0 @@
-#!/usr/bin/env perl
-# SPDX-License-Identifier: GPL-2.0
-# vim: softtabstop=4
-
-use warnings;
-use strict;
-
-## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
-## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
-## Copyright (C) 2001 Simon Huggins ##
-## Copyright (C) 2005-2012 Randy Dunlap ##
-## Copyright (C) 2012 Dan Luedtke ##
-## ##
-## #define enhancements by Armin Kuster <akuster@mvista.com> ##
-## Copyright (c) 2000 MontaVista Software, Inc. ##
-#
-# Copyright (C) 2022 Tomasz Warniełło (POD)
-
-use Pod::Usage qw/pod2usage/;
-
-=head1 NAME
-
-kernel-doc - Print formatted kernel documentation to stdout
-
-=head1 SYNOPSIS
-
- kernel-doc [-h] [-v] [-Werror] [-Wall] [-Wreturn] [-Wshort-desc[ription]] [-Wcontents-before-sections]
- [ -man |
- -rst [-enable-lineno] |
- -none
- ]
- [
- -export |
- -internal |
- [-function NAME] ... |
- [-nosymbol NAME] ...
- ]
- [-no-doc-sections]
- [-export-file FILE] ...
- FILE ...
-
-Run `kernel-doc -h` for details.
-
-=head1 DESCRIPTION
-
-Read C language source or header FILEs, extract embedded documentation comments,
-and print formatted documentation to standard output.
-
-The documentation comments are identified by the "/**" opening comment mark.
-
-See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
-
-=cut
-
-# more perldoc at the end of the file
-
-## init lots of data
-
-my $errors = 0;
-my $warnings = 0;
-my $anon_struct_union = 0;
-
-# match expressions used to find embedded type information
-my $type_constant = '\b``([^\`]+)``\b';
-my $type_constant2 = '\%([-_*\w]+)';
-my $type_func = '(\w+)\(\)';
-my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
-my $type_param_ref = '([\!~\*]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
-my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params
-my $type_fp_param2 = '\@(\w+->\S+)\(\)'; # Special RST handling for structs with func ptr params
-my $type_env = '(\$\w+)';
-my $type_enum = '\&(enum\s*([_\w]+))';
-my $type_struct = '\&(struct\s*([_\w]+))';
-my $type_typedef = '\&(typedef\s*([_\w]+))';
-my $type_union = '\&(union\s*([_\w]+))';
-my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
-my $type_fallback = '\&([_\w]+)';
-my $type_member_func = $type_member . '\(\)';
-
-# Output conversion substitutions.
-# One for each output format
-
-# these are pretty rough
-my @highlights_man = (
- [$type_constant, "\$1"],
- [$type_constant2, "\$1"],
- [$type_func, "\\\\fB\$1\\\\fP"],
- [$type_enum, "\\\\fI\$1\\\\fP"],
- [$type_struct, "\\\\fI\$1\\\\fP"],
- [$type_typedef, "\\\\fI\$1\\\\fP"],
- [$type_union, "\\\\fI\$1\\\\fP"],
- [$type_param, "\\\\fI\$1\\\\fP"],
- [$type_param_ref, "\\\\fI\$1\$2\\\\fP"],
- [$type_member, "\\\\fI\$1\$2\$3\\\\fP"],
- [$type_fallback, "\\\\fI\$1\\\\fP"]
- );
-my $blankline_man = "";
-
-# rst-mode
-my @highlights_rst = (
- [$type_constant, "``\$1``"],
- [$type_constant2, "``\$1``"],
-
- # Note: need to escape () to avoid func matching later
- [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"],
- [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
- [$type_fp_param, "**\$1\\\\(\\\\)**"],
- [$type_fp_param2, "**\$1\\\\(\\\\)**"],
- [$type_func, "\$1()"],
- [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],
- [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],
- [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"],
- [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"],
-
- # in rst this can refer to any type
- [$type_fallback, "\\:c\\:type\\:`\$1`"],
- [$type_param_ref, "**\$1\$2**"]
- );
-my $blankline_rst = "\n";
-
-# read arguments
-if ($#ARGV == -1) {
- pod2usage(
- -message => "No arguments!\n",
- -exitval => 1,
- -verbose => 99,
- -sections => 'SYNOPSIS',
- -output => \*STDERR,
- );
-}
-
-my $kernelversion;
-
-my $dohighlight = "";
-
-my $verbose = 0;
-my $Werror = 0;
-my $Wreturn = 0;
-my $Wshort_desc = 0;
-my $output_mode = "rst";
-my $output_preformatted = 0;
-my $no_doc_sections = 0;
-my $enable_lineno = 0;
-my @highlights = @highlights_rst;
-my $blankline = $blankline_rst;
-my $modulename = "Kernel API";
-
-use constant {
- OUTPUT_ALL => 0, # output all symbols and doc sections
- OUTPUT_INCLUDE => 1, # output only specified symbols
- OUTPUT_EXPORTED => 2, # output exported symbols
- OUTPUT_INTERNAL => 3, # output non-exported symbols
-};
-my $output_selection = OUTPUT_ALL;
-my $show_not_found = 0; # No longer used
-
-my @export_file_list;
-
-my @build_time;
-if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
- (my $seconds = `date -d "${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
- @build_time = gmtime($seconds);
-} else {
- @build_time = localtime;
-}
-
-my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
- 'July', 'August', 'September', 'October',
- 'November', 'December')[$build_time[4]] .
- " " . ($build_time[5]+1900);
-
-# Essentially these are globals.
-# They probably want to be tidied up, made more localised or something.
-# CAVEAT EMPTOR! Some of the others I localised may not want to be, which
-# could cause "use of undefined value" or other bugs.
-my ($function, %function_table, %parametertypes, $declaration_purpose);
-my %nosymbol_table = ();
-my $declaration_start_line;
-my ($type, $declaration_name, $return_type);
-my ($newsection, $newcontents, $prototype, $brcount);
-
-if (defined($ENV{'KBUILD_VERBOSE'}) && $ENV{'KBUILD_VERBOSE'} =~ '1') {
- $verbose = 1;
-}
-
-if (defined($ENV{'KCFLAGS'})) {
- my $kcflags = "$ENV{'KCFLAGS'}";
-
- if ($kcflags =~ /(\s|^)-Werror(\s|$)/) {
- $Werror = 1;
- }
-}
-
-# reading this variable is for backwards compat just in case
-# someone was calling it with the variable from outside the
-# kernel's build system
-if (defined($ENV{'KDOC_WERROR'})) {
- $Werror = "$ENV{'KDOC_WERROR'}";
-}
-# other environment variables are converted to command-line
-# arguments in cmd_checkdoc in the build system
-
-# Generated docbook code is inserted in a template at a point where
-# docbook v3.1 requires a non-zero sequence of RefEntry's; see:
-# https://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
-# We keep track of number of generated entries and generate a dummy
-# if needs be to ensure the expanded template can be postprocessed
-# into html.
-my $section_counter = 0;
-
-my $lineprefix="";
-
-# Parser states
-use constant {
- STATE_NORMAL => 0, # normal code
- STATE_NAME => 1, # looking for function name
- STATE_BODY_MAYBE => 2, # body - or maybe more description
- STATE_BODY => 3, # the body of the comment
- STATE_BODY_WITH_BLANK_LINE => 4, # the body, which has a blank line
- STATE_PROTO => 5, # scanning prototype
- STATE_DOCBLOCK => 6, # documentation block
- STATE_INLINE => 7, # gathering doc outside main block
-};
-my $state;
-my $leading_space;
-
-# Inline documentation state
-use constant {
- STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE)
- STATE_INLINE_NAME => 1, # looking for member name (@foo:)
- STATE_INLINE_TEXT => 2, # looking for member documentation
- STATE_INLINE_END => 3, # done
- STATE_INLINE_ERROR => 4, # error - Comment without header was found.
- # Spit a warning as it's not
- # proper kernel-doc and ignore the rest.
-};
-my $inline_doc_state;
-
-#declaration types: can be
-# 'function', 'struct', 'union', 'enum', 'typedef'
-my $decl_type;
-
-# Name of the kernel-doc identifier for non-DOC markups
-my $identifier;
-
-my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
-my $doc_end = '\*/';
-my $doc_com = '\s*\*\s*';
-my $doc_com_body = '\s*\* ?';
-my $doc_decl = $doc_com . '(\w+)';
-# @params and a strictly limited set of supported section names
-# Specifically:
-# Match @word:
-# @...:
-# @{section-name}:
-# while trying to not match literal block starts like "example::"
-#
-my $doc_sect = $doc_com .
- '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:([^:].*)?$';
-my $doc_content = $doc_com_body . '(.*)';
-my $doc_block = $doc_com . 'DOC:\s*(.*)?';
-my $doc_inline_start = '^\s*/\*\*\s*$';
-my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
-my $doc_inline_end = '^\s*\*/\s*$';
-my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
-my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
-my $export_symbol_ns = '^\s*EXPORT_SYMBOL_NS(_GPL)?\s*\(\s*(\w+)\s*,\s*"\S+"\)\s*;';
-my $function_pointer = qr{([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)};
-my $attribute = qr{__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)}i;
-
-my %parameterdescs;
-my %parameterdesc_start_lines;
-my @parameterlist;
-my %sections;
-my @sectionlist;
-my %section_start_lines;
-my $sectcheck;
-my $struct_actual;
-
-my $contents = "";
-my $new_start_line = 0;
-
-# the canonical section names. see also $doc_sect above.
-my $section_default = "Description"; # default section
-my $section_intro = "Introduction";
-my $section = $section_default;
-my $section_context = "Context";
-my $section_return = "Return";
-
-my $undescribed = "-- undescribed --";
-
-reset_state();
-
-while ($ARGV[0] =~ m/^--?(.*)/) {
- my $cmd = $1;
- shift @ARGV;
- if ($cmd eq "man") {
- $output_mode = "man";
- @highlights = @highlights_man;
- $blankline = $blankline_man;
- } elsif ($cmd eq "rst") {
- $output_mode = "rst";
- @highlights = @highlights_rst;
- $blankline = $blankline_rst;
- } elsif ($cmd eq "none") {
- $output_mode = "none";
- } elsif ($cmd eq "module") { # not needed for XML, inherits from calling document
- $modulename = shift @ARGV;
- } elsif ($cmd eq "function") { # to only output specific functions
- $output_selection = OUTPUT_INCLUDE;
- $function = shift @ARGV;
- $function_table{$function} = 1;
- } elsif ($cmd eq "nosymbol") { # Exclude specific symbols
- my $symbol = shift @ARGV;
- $nosymbol_table{$symbol} = 1;
- } elsif ($cmd eq "export") { # only exported symbols
- $output_selection = OUTPUT_EXPORTED;
- %function_table = ();
- } elsif ($cmd eq "internal") { # only non-exported symbols
- $output_selection = OUTPUT_INTERNAL;
- %function_table = ();
- } elsif ($cmd eq "export-file") {
- my $file = shift @ARGV;
- push(@export_file_list, $file);
- } elsif ($cmd eq "v") {
- $verbose = 1;
- } elsif ($cmd eq "Werror") {
- $Werror = 1;
- } elsif ($cmd eq "Wreturn") {
- $Wreturn = 1;
- } elsif ($cmd eq "Wshort-desc" or $cmd eq "Wshort-description") {
- $Wshort_desc = 1;
- } elsif ($cmd eq "Wall") {
- $Wreturn = 1;
- $Wshort_desc = 1;
- } elsif (($cmd eq "h") || ($cmd eq "help")) {
- pod2usage(-exitval => 0, -verbose => 2);
- } elsif ($cmd eq 'no-doc-sections') {
- $no_doc_sections = 1;
- } elsif ($cmd eq 'enable-lineno') {
- $enable_lineno = 1;
- } elsif ($cmd eq 'show-not-found') {
- $show_not_found = 1; # A no-op but don't fail
- } else {
- # Unknown argument
- pod2usage(
- -message => "Argument unknown!\n",
- -exitval => 1,
- -verbose => 99,
- -sections => 'SYNOPSIS',
- -output => \*STDERR,
- );
- }
- if ($#ARGV < 0){
- pod2usage(
- -message => "FILE argument missing\n",
- -exitval => 1,
- -verbose => 99,
- -sections => 'SYNOPSIS',
- -output => \*STDERR,
- );
- }
-}
-
-# continue execution near EOF;
-
-sub findprog($)
-{
- foreach(split(/:/, $ENV{PATH})) {
- return "$_/$_[0]" if(-x "$_/$_[0]");
- }
-}
-
-# get kernel version from env
-sub get_kernel_version() {
- my $version = 'unknown kernel version';
-
- if (defined($ENV{'KERNELVERSION'})) {
- $version = $ENV{'KERNELVERSION'};
- }
- return $version;
-}
-
-#
-sub print_lineno {
- my $lineno = shift;
- if ($enable_lineno && defined($lineno)) {
- print ".. LINENO " . $lineno . "\n";
- }
-}
-
-sub emit_warning {
- my $location = shift;
- my $msg = shift;
- print STDERR "$location: warning: $msg";
- ++$warnings;
-}
-##
-# dumps section contents to arrays/hashes intended for that purpose.
-#
-sub dump_section {
- my $file = shift;
- my $name = shift;
- my $contents = join "\n", @_;
-
- if ($name =~ m/$type_param/) {
- $name = $1;
- $parameterdescs{$name} = $contents;
- $sectcheck = $sectcheck . $name . " ";
- $parameterdesc_start_lines{$name} = $new_start_line;
- $new_start_line = 0;
- } elsif ($name eq "@\.\.\.") {
- $name = "...";
- $parameterdescs{$name} = $contents;
- $sectcheck = $sectcheck . $name . " ";
- $parameterdesc_start_lines{$name} = $new_start_line;
- $new_start_line = 0;
- } else {
- if (defined($sections{$name}) && ($sections{$name} ne "")) {
- # Only warn on user specified duplicate section names.
- if ($name ne $section_default) {
- emit_warning("${file}:$.", "duplicate section name '$name'\n");
- }
- $sections{$name} .= $contents;
- } else {
- $sections{$name} = $contents;
- push @sectionlist, $name;
- $section_start_lines{$name} = $new_start_line;
- $new_start_line = 0;
- }
- }
-}
-
-##
-# dump DOC: section after checking that it should go out
-#
-sub dump_doc_section {
- my $file = shift;
- my $name = shift;
- my $contents = join "\n", @_;
-
- if ($no_doc_sections) {
- return;
- }
-
- return if (defined($nosymbol_table{$name}));
-
- if (($output_selection == OUTPUT_ALL) ||
- (($output_selection == OUTPUT_INCLUDE) &&
- defined($function_table{$name})))
- {
- dump_section($file, $name, $contents);
- output_blockhead({'sectionlist' => \@sectionlist,
- 'sections' => \%sections,
- 'module' => $modulename,
- 'content-only' => ($output_selection != OUTPUT_ALL), });
- }
-}
-
-##
-# output function
-#
-# parameterdescs, a hash.
-# function => "function name"
-# parameterlist => @list of parameters
-# parameterdescs => %parameter descriptions
-# sectionlist => @list of sections
-# sections => %section descriptions
-#
-
-sub output_highlight {
- my $contents = join "\n",@_;
- my $line;
-
-# DEBUG
-# if (!defined $contents) {
-# use Carp;
-# confess "output_highlight got called with no args?\n";
-# }
-
-# print STDERR "contents b4:$contents\n";
- eval $dohighlight;
- die $@ if $@;
-# print STDERR "contents af:$contents\n";
-
- foreach $line (split "\n", $contents) {
- if (! $output_preformatted) {
- $line =~ s/^\s*//;
- }
- if ($line eq ""){
- if (! $output_preformatted) {
- print $lineprefix, $blankline;
- }
- } else {
- if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
- print "\\&$line";
- } else {
- print $lineprefix, $line;
- }
- }
- print "\n";
- }
-}
-
-##
-# output function in man
-sub output_function_man(%) {
- my %args = %{$_[0]};
- my ($parameter, $section);
- my $count;
- my $func_macro = $args{'func_macro'};
- my $paramcount = $#{$args{'parameterlist'}}; # -1 is empty
-
- print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
-
- print ".SH NAME\n";
- print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
-
- print ".SH SYNOPSIS\n";
- if ($args{'functiontype'} ne "") {
- print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
- } else {
- print ".B \"" . $args{'function'} . "\n";
- }
- $count = 0;
- my $parenth = "(";
- my $post = ",";
- foreach my $parameter (@{$args{'parameterlist'}}) {
- if ($count == $#{$args{'parameterlist'}}) {
- $post = ");";
- }
- $type = $args{'parametertypes'}{$parameter};
- if ($type =~ m/$function_pointer/) {
- # pointer-to-function
- print ".BI \"" . $parenth . $1 . "\" " . " \") (" . $2 . ")" . $post . "\"\n";
- } else {
- $type =~ s/([^\*])$/$1 /;
- print ".BI \"" . $parenth . $type . "\" " . " \"" . $post . "\"\n";
- }
- $count++;
- $parenth = "";
- }
-
- $paramcount = $#{$args{'parameterlist'}}; # -1 is empty
- if ($paramcount >= 0) {
- print ".SH ARGUMENTS\n";
- }
- foreach $parameter (@{$args{'parameterlist'}}) {
- my $parameter_name = $parameter;
- $parameter_name =~ s/\[.*//;
-
- print ".IP \"" . $parameter . "\" 12\n";
- output_highlight($args{'parameterdescs'}{$parameter_name});
- }
- foreach $section (@{$args{'sectionlist'}}) {
- print ".SH \"", uc $section, "\"\n";
- output_highlight($args{'sections'}{$section});
- }
-}
-
-##
-# output enum in man
-sub output_enum_man(%) {
- my %args = %{$_[0]};
- my ($parameter, $section);
- my $count;
-
- print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
-
- print ".SH NAME\n";
- print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
-
- print ".SH SYNOPSIS\n";
- print "enum " . $args{'enum'} . " {\n";
- $count = 0;
- foreach my $parameter (@{$args{'parameterlist'}}) {
- print ".br\n.BI \" $parameter\"\n";
- if ($count == $#{$args{'parameterlist'}}) {
- print "\n};\n";
- last;
- } else {
- print ", \n.br\n";
- }
- $count++;
- }
-
- print ".SH Constants\n";
- foreach $parameter (@{$args{'parameterlist'}}) {
- my $parameter_name = $parameter;
- $parameter_name =~ s/\[.*//;
-
- print ".IP \"" . $parameter . "\" 12\n";
- output_highlight($args{'parameterdescs'}{$parameter_name});
- }
- foreach $section (@{$args{'sectionlist'}}) {
- print ".SH \"$section\"\n";
- output_highlight($args{'sections'}{$section});
- }
-}
-
-##
-# output struct in man
-sub output_struct_man(%) {
- my %args = %{$_[0]};
- my ($parameter, $section);
-
- print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";
-
- print ".SH NAME\n";
- print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
-
- my $declaration = $args{'definition'};
- $declaration =~ s/\t/ /g;
- $declaration =~ s/\n/"\n.br\n.BI \"/g;
- print ".SH SYNOPSIS\n";
- print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
- print ".BI \"$declaration\n};\n.br\n\n";
-
- print ".SH Members\n";
- foreach $parameter (@{$args{'parameterlist'}}) {
- ($parameter =~ /^#/) && next;
-
- my $parameter_name = $parameter;
- $parameter_name =~ s/\[.*//;
-
- ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
- print ".IP \"" . $parameter . "\" 12\n";
- output_highlight($args{'parameterdescs'}{$parameter_name});
- }
- foreach $section (@{$args{'sectionlist'}}) {
- print ".SH \"$section\"\n";
- output_highlight($args{'sections'}{$section});
- }
-}
-
-##
-# output typedef in man
-sub output_typedef_man(%) {
- my %args = %{$_[0]};
- my ($parameter, $section);
-
- print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
-
- print ".SH NAME\n";
- print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
-
- foreach $section (@{$args{'sectionlist'}}) {
- print ".SH \"$section\"\n";
- output_highlight($args{'sections'}{$section});
- }
-}
-
-sub output_blockhead_man(%) {
- my %args = %{$_[0]};
- my ($parameter, $section);
- my $count;
-
- print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
-
- foreach $section (@{$args{'sectionlist'}}) {
- print ".SH \"$section\"\n";
- output_highlight($args{'sections'}{$section});
- }
-}
-
-##
-# output in restructured text
-#
-
-#
-# This could use some work; it's used to output the DOC: sections, and
-# starts by putting out the name of the doc section itself, but that tends
-# to duplicate a header already in the template file.
-#
-sub output_blockhead_rst(%) {
- my %args = %{$_[0]};
- my ($parameter, $section);
-
- foreach $section (@{$args{'sectionlist'}}) {
- next if (defined($nosymbol_table{$section}));
-
- if ($output_selection != OUTPUT_INCLUDE) {
- print ".. _$section:\n\n";
- print "**$section**\n\n";
- }
- print_lineno($section_start_lines{$section});
- output_highlight_rst($args{'sections'}{$section});
- print "\n";
- }
-}
-
-#
-# Apply the RST highlights to a sub-block of text.
-#
-sub highlight_block($) {
- # The dohighlight kludge requires the text be called $contents
- my $contents = shift;
- eval $dohighlight;
- die $@ if $@;
- return $contents;
-}
-
-#
-# Regexes used only here.
-#
-my $sphinx_literal = '^[^.].*::$';
-my $sphinx_cblock = '^\.\.\ +code-block::';
-
-sub output_highlight_rst {
- my $input = join "\n",@_;
- my $output = "";
- my $line;
- my $in_literal = 0;
- my $litprefix;
- my $block = "";
-
- foreach $line (split "\n",$input) {
- #
- # If we're in a literal block, see if we should drop out
- # of it. Otherwise pass the line straight through unmunged.
- #
- if ($in_literal) {
- if (! ($line =~ /^\s*$/)) {
- #
- # If this is the first non-blank line in a literal
- # block we need to figure out what the proper indent is.
- #
- if ($litprefix eq "") {
- $line =~ /^(\s*)/;
- $litprefix = '^' . $1;
- $output .= $line . "\n";
- } elsif (! ($line =~ /$litprefix/)) {
- $in_literal = 0;
- } else {
- $output .= $line . "\n";
- }
- } else {
- $output .= $line . "\n";
- }
- }
- #
- # Not in a literal block (or just dropped out)
- #
- if (! $in_literal) {
- $block .= $line . "\n";
- if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) {
- $in_literal = 1;
- $litprefix = "";
- $output .= highlight_block($block);
- $block = ""
- }
- }
- }
-
- if ($block) {
- $output .= highlight_block($block);
- }
-
- $output =~ s/^\n+//g;
- $output =~ s/\n+$//g;
-
- foreach $line (split "\n", $output) {
- print $lineprefix . $line . "\n";
- }
-}
-
-sub output_function_rst(%) {
- my %args = %{$_[0]};
- my ($parameter, $section);
- my $oldprefix = $lineprefix;
-
- my $signature = "";
- my $func_macro = $args{'func_macro'};
- my $paramcount = $#{$args{'parameterlist'}}; # -1 is empty
-
- if ($func_macro) {
- $signature = $args{'function'};
- } else {
- if ($args{'functiontype'}) {
- $signature = $args{'functiontype'} . " ";
- }
- $signature .= $args{'function'} . " (";
- }
-
- my $count = 0;
- foreach my $parameter (@{$args{'parameterlist'}}) {
- if ($count ne 0) {
- $signature .= ", ";
- }
- $count++;
- $type = $args{'parametertypes'}{$parameter};
-
- if ($type =~ m/$function_pointer/) {
- # pointer-to-function
- $signature .= $1 . $parameter . ") (" . $2 . ")";
- } else {
- $signature .= $type;
- }
- }
-
- if (!$func_macro) {
- $signature .= ")";
- }
-
- if ($args{'typedef'} || $args{'functiontype'} eq "") {
- print ".. c:macro:: ". $args{'function'} . "\n\n";
-
- if ($args{'typedef'}) {
- print_lineno($declaration_start_line);
- print " **Typedef**: ";
- $lineprefix = "";
- output_highlight_rst($args{'purpose'});
- print "\n\n**Syntax**\n\n";
- print " ``$signature``\n\n";
- } else {
- print "``$signature``\n\n";
- }
- } else {
- print ".. c:function:: $signature\n\n";
- }
-
- if (!$args{'typedef'}) {
- print_lineno($declaration_start_line);
- $lineprefix = " ";
- output_highlight_rst($args{'purpose'});
- print "\n";
- }
-
- #
- # Put our descriptive text into a container (thus an HTML <div>) to help
- # set the function prototypes apart.
- #
- $lineprefix = " ";
- if ($paramcount >= 0) {
- print ".. container:: kernelindent\n\n";
- print $lineprefix . "**Parameters**\n\n";
- }
- foreach $parameter (@{$args{'parameterlist'}}) {
- my $parameter_name = $parameter;
- $parameter_name =~ s/\[.*//;
- $type = $args{'parametertypes'}{$parameter};
-
- if ($type ne "") {
- print $lineprefix . "``$type``\n";
- } else {
- print $lineprefix . "``$parameter``\n";
- }
-
- print_lineno($parameterdesc_start_lines{$parameter_name});
-
- $lineprefix = " ";
- if (defined($args{'parameterdescs'}{$parameter_name}) &&
- $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
- output_highlight_rst($args{'parameterdescs'}{$parameter_name});
- } else {
- print $lineprefix . "*undescribed*\n";
- }
- $lineprefix = " ";
- print "\n";
- }
-
- output_section_rst(@_);
- $lineprefix = $oldprefix;
-}
-
-sub output_section_rst(%) {
- my %args = %{$_[0]};
- my $section;
- my $oldprefix = $lineprefix;
-
- foreach $section (@{$args{'sectionlist'}}) {
- print $lineprefix . "**$section**\n\n";
- print_lineno($section_start_lines{$section});
- output_highlight_rst($args{'sections'}{$section});
- print "\n";
- }
- print "\n";
-}
-
-sub output_enum_rst(%) {
- my %args = %{$_[0]};
- my ($parameter);
- my $oldprefix = $lineprefix;
- my $count;
- my $outer;
-
- my $name = $args{'enum'};
- print "\n\n.. c:enum:: " . $name . "\n\n";
-
- print_lineno($declaration_start_line);
- $lineprefix = " ";
- output_highlight_rst($args{'purpose'});
- print "\n";
-
- print ".. container:: kernelindent\n\n";
- $outer = $lineprefix . " ";
- $lineprefix = $outer . " ";
- print $outer . "**Constants**\n\n";
- foreach $parameter (@{$args{'parameterlist'}}) {
- print $outer . "``$parameter``\n";
-
- if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
- output_highlight_rst($args{'parameterdescs'}{$parameter});
- } else {
- print $lineprefix . "*undescribed*\n";
- }
- print "\n";
- }
- print "\n";
- $lineprefix = $oldprefix;
- output_section_rst(@_);
-}
-
-sub output_typedef_rst(%) {
- my %args = %{$_[0]};
- my ($parameter);
- my $oldprefix = $lineprefix;
- my $name;
-
- $name = $args{'typedef'};
-
- print "\n\n.. c:type:: " . $name . "\n\n";
- print_lineno($declaration_start_line);
- $lineprefix = " ";
- output_highlight_rst($args{'purpose'});
- print "\n";
-
- $lineprefix = $oldprefix;
- output_section_rst(@_);
-}
-
-sub output_struct_rst(%) {
- my %args = %{$_[0]};
- my ($parameter);
- my $oldprefix = $lineprefix;
-
- my $name = $args{'struct'};
- if ($args{'type'} eq 'union') {
- print "\n\n.. c:union:: " . $name . "\n\n";
- } else {
- print "\n\n.. c:struct:: " . $name . "\n\n";
- }
-
- print_lineno($declaration_start_line);
- $lineprefix = " ";
- output_highlight_rst($args{'purpose'});
- print "\n";
-
- print ".. container:: kernelindent\n\n";
- print $lineprefix . "**Definition**::\n\n";
- my $declaration = $args{'definition'};
- $lineprefix = $lineprefix . " ";
- $declaration =~ s/\t/$lineprefix/g;
- print $lineprefix . $args{'type'} . " " . $args{'struct'} . " {\n$declaration" . $lineprefix . "};\n\n";
-
- $lineprefix = " ";
- print $lineprefix . "**Members**\n\n";
- foreach $parameter (@{$args{'parameterlist'}}) {
- ($parameter =~ /^#/) && next;
-
- my $parameter_name = $parameter;
- $parameter_name =~ s/\[.*//;
-
- ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
- $type = $args{'parametertypes'}{$parameter};
- print_lineno($parameterdesc_start_lines{$parameter_name});
- print $lineprefix . "``" . $parameter . "``\n";
- $lineprefix = " ";
- output_highlight_rst($args{'parameterdescs'}{$parameter_name});
- $lineprefix = " ";
- print "\n";
- }
- print "\n";
-
- $lineprefix = $oldprefix;
- output_section_rst(@_);
-}
-
-## none mode output functions
-
-sub output_function_none(%) {
-}
-
-sub output_enum_none(%) {
-}
-
-sub output_typedef_none(%) {
-}
-
-sub output_struct_none(%) {
-}
-
-sub output_blockhead_none(%) {
-}
-
-##
-# generic output function for all types (function, struct/union, typedef, enum);
-# calls the generated, variable output_ function name based on
-# functype and output_mode
-sub output_declaration {
- no strict 'refs';
- my $name = shift;
- my $functype = shift;
- my $func = "output_${functype}_$output_mode";
-
- return if (defined($nosymbol_table{$name}));
-
- if (($output_selection == OUTPUT_ALL) ||
- (($output_selection == OUTPUT_INCLUDE ||
- $output_selection == OUTPUT_EXPORTED) &&
- defined($function_table{$name})) ||
- ($output_selection == OUTPUT_INTERNAL &&
- !($functype eq "function" && defined($function_table{$name}))))
- {
- &$func(@_);
- $section_counter++;
- }
-}
-
-##
-# generic output function - calls the right one based on current output mode.
-sub output_blockhead {
- no strict 'refs';
- my $func = "output_blockhead_" . $output_mode;
- &$func(@_);
- $section_counter++;
-}
-
-##
-# takes a declaration (struct, union, enum, typedef) and
-# invokes the right handler. NOT called for functions.
-sub dump_declaration($$) {
- no strict 'refs';
- my ($prototype, $file) = @_;
- my $func = "dump_" . $decl_type;
- &$func(@_);
-}
-
-sub dump_union($$) {
- dump_struct(@_);
-}
-
-sub dump_struct($$) {
- my $x = shift;
- my $file = shift;
- my $decl_type;
- my $members;
- my $type = qr{struct|union};
- # For capturing struct/union definition body, i.e. "{members*}qualifiers*"
- my $qualifiers = qr{$attribute|__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned};
- my $definition_body = qr{\{(.*)\}\s*$qualifiers*};
- my $struct_members = qr{($type)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;};
-
- if ($x =~ /($type)\s+(\w+)\s*$definition_body/) {
- $decl_type = $1;
- $declaration_name = $2;
- $members = $3;
- } elsif ($x =~ /typedef\s+($type)\s*$definition_body\s*(\w+)\s*;/) {
- $decl_type = $1;
- $declaration_name = $3;
- $members = $2;
- }
-
- if ($members) {
- if ($identifier ne $declaration_name) {
- emit_warning("${file}:$.", "expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n");
- return;
- }
-
- # ignore members marked private:
- $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
- $members =~ s/\/\*\s*private:.*//gosi;
- # strip comments:
- $members =~ s/\/\*.*?\*\///gos;
- # strip attributes
- $members =~ s/\s*$attribute/ /gi;
- $members =~ s/\s*__aligned\s*\([^;]*\)/ /gos;
- $members =~ s/\s*__counted_by\s*\([^;]*\)/ /gos;
- $members =~ s/\s*__counted_by_(le|be)\s*\([^;]*\)/ /gos;
- $members =~ s/\s*__packed\s*/ /gos;
- $members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos;
- $members =~ s/\s*____cacheline_aligned_in_smp/ /gos;
- $members =~ s/\s*____cacheline_aligned/ /gos;
- # unwrap struct_group():
- # - first eat non-declaration parameters and rewrite for final match
- # - then remove macro, outer parens, and trailing semicolon
- $members =~ s/\bstruct_group\s*\(([^,]*,)/STRUCT_GROUP(/gos;
- $members =~ s/\bstruct_group_attr\s*\(([^,]*,){2}/STRUCT_GROUP(/gos;
- $members =~ s/\bstruct_group_tagged\s*\(([^,]*),([^,]*),/struct $1 $2; STRUCT_GROUP(/gos;
- $members =~ s/\b__struct_group\s*\(([^,]*,){3}/STRUCT_GROUP(/gos;
- $members =~ s/\bSTRUCT_GROUP(\(((?:(?>[^)(]+)|(?1))*)\))[^;]*;/$2/gos;
-
- my $args = qr{([^,)]+)};
- # replace DECLARE_BITMAP
- $members =~ s/__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)/DECLARE_BITMAP($1, __ETHTOOL_LINK_MODE_MASK_NBITS)/gos;
- $members =~ s/DECLARE_PHY_INTERFACE_MASK\s*\(([^\)]+)\)/DECLARE_BITMAP($1, PHY_INTERFACE_MODE_MAX)/gos;
- $members =~ s/DECLARE_BITMAP\s*\($args,\s*$args\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
- # replace DECLARE_HASHTABLE
- $members =~ s/DECLARE_HASHTABLE\s*\($args,\s*$args\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
- # replace DECLARE_KFIFO
- $members =~ s/DECLARE_KFIFO\s*\($args,\s*$args,\s*$args\)/$2 \*$1/gos;
- # replace DECLARE_KFIFO_PTR
- $members =~ s/DECLARE_KFIFO_PTR\s*\($args,\s*$args\)/$2 \*$1/gos;
- # replace DECLARE_FLEX_ARRAY
- $members =~ s/(?:__)?DECLARE_FLEX_ARRAY\s*\($args,\s*$args\)/$1 $2\[\]/gos;
- #replace DEFINE_DMA_UNMAP_ADDR
- $members =~ s/DEFINE_DMA_UNMAP_ADDR\s*\($args\)/dma_addr_t $1/gos;
- #replace DEFINE_DMA_UNMAP_LEN
- $members =~ s/DEFINE_DMA_UNMAP_LEN\s*\($args\)/__u32 $1/gos;
- my $declaration = $members;
-
- # Split nested struct/union elements as newer ones
- while ($members =~ m/$struct_members/) {
- my $newmember;
- my $maintype = $1;
- my $ids = $4;
- my $content = $3;
- foreach my $id(split /,/, $ids) {
- $newmember .= "$maintype $id; ";
-
- $id =~ s/[:\[].*//;
- $id =~ s/^\s*\**(\S+)\s*/$1/;
- foreach my $arg (split /;/, $content) {
- next if ($arg =~ m/^\s*$/);
- if ($arg =~ m/^([^\(]+\(\*?\s*)([\w\.]*)(\s*\).*)/) {
- # pointer-to-function
- my $type = $1;
- my $name = $2;
- my $extra = $3;
- next if (!$name);
- if ($id =~ m/^\s*$/) {
- # anonymous struct/union
- $newmember .= "$type$name$extra; ";
- } else {
- $newmember .= "$type$id.$name$extra; ";
- }
- } else {
- my $type;
- my $names;
- $arg =~ s/^\s+//;
- $arg =~ s/\s+$//;
- # Handle bitmaps
- $arg =~ s/:\s*\d+\s*//g;
- # Handle arrays
- $arg =~ s/\[.*\]//g;
- # The type may have multiple words,
- # and multiple IDs can be defined, like:
- # const struct foo, *bar, foobar
- # So, we remove spaces when parsing the
- # names, in order to match just names
- # and commas for the names
- $arg =~ s/\s*,\s*/,/g;
- if ($arg =~ m/(.*)\s+([\S+,]+)/) {
- $type = $1;
- $names = $2;
- } else {
- $newmember .= "$arg; ";
- next;
- }
- foreach my $name (split /,/, $names) {
- $name =~ s/^\s*\**(\S+)\s*/$1/;
- next if (($name =~ m/^\s*$/));
- if ($id =~ m/^\s*$/) {
- # anonymous struct/union
- $newmember .= "$type $name; ";
- } else {
- $newmember .= "$type $id.$name; ";
- }
- }
- }
- }
- }
- $members =~ s/$struct_members/$newmember/;
- }
-
- # Ignore other nested elements, like enums
- $members =~ s/(\{[^\{\}]*\})//g;
-
- create_parameterlist($members, ';', $file, $declaration_name);
- check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual);
-
- # Adjust declaration for better display
- $declaration =~ s/([\{;])/$1\n/g;
- $declaration =~ s/\}\s+;/};/g;
- # Better handle inlined enums
- do {} while ($declaration =~ s/(enum\s+\{[^\}]+),([^\n])/$1,\n$2/);
-
- my @def_args = split /\n/, $declaration;
- my $level = 1;
- $declaration = "";
- foreach my $clause (@def_args) {
- $clause =~ s/^\s+//;
- $clause =~ s/\s+$//;
- $clause =~ s/\s+/ /;
- next if (!$clause);
- $level-- if ($clause =~ m/(\})/ && $level > 1);
- if (!($clause =~ m/^\s*#/)) {
- $declaration .= "\t" x $level;
- }
- $declaration .= "\t" . $clause . "\n";
- $level++ if ($clause =~ m/(\{)/ && !($clause =~m/\}/));
- }
- output_declaration($declaration_name,
- 'struct',
- {'struct' => $declaration_name,
- 'module' => $modulename,
- 'definition' => $declaration,
- 'parameterlist' => \@parameterlist,
- 'parameterdescs' => \%parameterdescs,
- 'parametertypes' => \%parametertypes,
- 'sectionlist' => \@sectionlist,
- 'sections' => \%sections,
- 'purpose' => $declaration_purpose,
- 'type' => $decl_type
- });
- } else {
- print STDERR "${file}:$.: error: Cannot parse struct or union!\n";
- ++$errors;
- }
-}
-
-
-sub show_warnings($$) {
- my $functype = shift;
- my $name = shift;
-
- return 0 if (defined($nosymbol_table{$name}));
-
- return 1 if ($output_selection == OUTPUT_ALL);
-
- if ($output_selection == OUTPUT_EXPORTED) {
- if (defined($function_table{$name})) {
- return 1;
- } else {
- return 0;
- }
- }
- if ($output_selection == OUTPUT_INTERNAL) {
- if (!($functype eq "function" && defined($function_table{$name}))) {
- return 1;
- } else {
- return 0;
- }
- }
- if ($output_selection == OUTPUT_INCLUDE) {
- if (defined($function_table{$name})) {
- return 1;
- } else {
- return 0;
- }
- }
- die("Please add the new output type at show_warnings()");
-}
-
-sub dump_enum($$) {
- my $x = shift;
- my $file = shift;
- my $members;
-
- # ignore members marked private:
- $x =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
- $x =~ s/\/\*\s*private:.*}/}/gosi;
-
- $x =~ s@/\*.*?\*/@@gos; # strip comments.
- # strip #define macros inside enums
- $x =~ s@#\s*((define|ifdef|if)\s+|endif)[^;]*;@@gos;
-
- if ($x =~ /typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;/) {
- $declaration_name = $2;
- $members = $1;
- } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) {
- $declaration_name = $1;
- $members = $2;
- }
-
- if ($members) {
- if ($identifier ne $declaration_name) {
- if ($identifier eq "") {
- emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n");
- } else {
- emit_warning("${file}:$.", "expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n");
- }
- return;
- }
- $declaration_name = "(anonymous)" if ($declaration_name eq "");
-
- my %_members;
-
- $members =~ s/\s+$//;
- $members =~ s/\([^;]*?[\)]//g;
-
- foreach my $arg (split ',', $members) {
- $arg =~ s/^\s*(\w+).*/$1/;
- push @parameterlist, $arg;
- if (!$parameterdescs{$arg}) {
- $parameterdescs{$arg} = $undescribed;
- if (show_warnings("enum", $declaration_name)) {
- emit_warning("${file}:$.", "Enum value '$arg' not described in enum '$declaration_name'\n");
- }
- }
- $_members{$arg} = 1;
- }
-
- while (my ($k, $v) = each %parameterdescs) {
- if (!exists($_members{$k})) {
- if (show_warnings("enum", $declaration_name)) {
- emit_warning("${file}:$.", "Excess enum value '$k' description in '$declaration_name'\n");
- }
- }
- }
-
- output_declaration($declaration_name,
- 'enum',
- {'enum' => $declaration_name,
- 'module' => $modulename,
- 'parameterlist' => \@parameterlist,
- 'parameterdescs' => \%parameterdescs,
- 'sectionlist' => \@sectionlist,
- 'sections' => \%sections,
- 'purpose' => $declaration_purpose
- });
- } else {
- print STDERR "${file}:$.: error: Cannot parse enum!\n";
- ++$errors;
- }
-}
-
-my $typedef_type = qr { ((?:\s+[\w\*]+\b){0,7}\s+(?:\w+\b|\*+))\s* }x;
-my $typedef_ident = qr { \*?\s*(\w\S+)\s* }x;
-my $typedef_args = qr { \s*\((.*)\); }x;
-
-my $typedef1 = qr { typedef$typedef_type\($typedef_ident\)$typedef_args }x;
-my $typedef2 = qr { typedef$typedef_type$typedef_ident$typedef_args }x;
-
-sub dump_typedef($$) {
- my $x = shift;
- my $file = shift;
-
- $x =~ s@/\*.*?\*/@@gos; # strip comments.
-
- # Parse function typedef prototypes
- if ($x =~ $typedef1 || $x =~ $typedef2) {
- $return_type = $1;
- $declaration_name = $2;
- my $args = $3;
- $return_type =~ s/^\s+//;
-
- if ($identifier ne $declaration_name) {
- emit_warning("${file}:$.", "expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n");
- return;
- }
-
- create_parameterlist($args, ',', $file, $declaration_name);
-
- output_declaration($declaration_name,
- 'function',
- {'function' => $declaration_name,
- 'typedef' => 1,
- 'module' => $modulename,
- 'functiontype' => $return_type,
- 'parameterlist' => \@parameterlist,
- 'parameterdescs' => \%parameterdescs,
- 'parametertypes' => \%parametertypes,
- 'sectionlist' => \@sectionlist,
- 'sections' => \%sections,
- 'purpose' => $declaration_purpose
- });
- return;
- }
-
- while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
- $x =~ s/\(*.\)\s*;$/;/;
- $x =~ s/\[*.\]\s*;$/;/;
- }
-
- if ($x =~ /typedef.*\s+(\w+)\s*;/) {
- $declaration_name = $1;
-
- if ($identifier ne $declaration_name) {
- emit_warning("${file}:$.", "expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n");
- return;
- }
-
- output_declaration($declaration_name,
- 'typedef',
- {'typedef' => $declaration_name,
- 'module' => $modulename,
- 'sectionlist' => \@sectionlist,
- 'sections' => \%sections,
- 'purpose' => $declaration_purpose
- });
- } else {
- print STDERR "${file}:$.: error: Cannot parse typedef!\n";
- ++$errors;
- }
-}
-
-sub save_struct_actual($) {
- my $actual = shift;
-
- # strip all spaces from the actual param so that it looks like one string item
- $actual =~ s/\s*//g;
- $struct_actual = $struct_actual . $actual . " ";
-}
-
-sub create_parameterlist($$$$) {
- my $args = shift;
- my $splitter = shift;
- my $file = shift;
- my $declaration_name = shift;
- my $type;
- my $param;
-
- # temporarily replace commas inside function pointer definition
- my $arg_expr = qr{\([^\),]+};
- while ($args =~ /$arg_expr,/) {
- $args =~ s/($arg_expr),/$1#/g;
- }
-
- foreach my $arg (split($splitter, $args)) {
- # strip comments
- $arg =~ s/\/\*.*\*\///;
- # ignore argument attributes
- $arg =~ s/\sPOS0?\s/ /;
- # strip leading/trailing spaces
- $arg =~ s/^\s*//;
- $arg =~ s/\s*$//;
- $arg =~ s/\s+/ /;
-
- if ($arg =~ /^#/) {
- # Treat preprocessor directive as a typeless variable just to fill
- # corresponding data structures "correctly". Catch it later in
- # output_* subs.
- push_parameter($arg, "", "", $file);
- } elsif ($arg =~ m/\(.+\)\s*\(/) {
- # pointer-to-function
- $arg =~ tr/#/,/;
- $arg =~ m/[^\(]+\(\*?\s*([\w\[\]\.]*)\s*\)/;
- $param = $1;
- $type = $arg;
- $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
- save_struct_actual($param);
- push_parameter($param, $type, $arg, $file, $declaration_name);
- } elsif ($arg =~ m/\(.+\)\s*\[/) {
- # array-of-pointers
- $arg =~ tr/#/,/;
- $arg =~ m/[^\(]+\(\s*\*\s*([\w\[\]\.]*?)\s*(\s*\[\s*[\w]+\s*\]\s*)*\)/;
- $param = $1;
- $type = $arg;
- $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
- save_struct_actual($param);
- push_parameter($param, $type, $arg, $file, $declaration_name);
- } elsif ($arg) {
- $arg =~ s/\s*:\s*/:/g;
- $arg =~ s/\s*\[/\[/g;
-
- my @args = split('\s*,\s*', $arg);
- if ($args[0] =~ m/\*/) {
- $args[0] =~ s/(\*+)\s*/ $1/;
- }
-
- my @first_arg;
- if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
- shift @args;
- push(@first_arg, split('\s+', $1));
- push(@first_arg, $2);
- } else {
- @first_arg = split('\s+', shift @args);
- }
-
- unshift(@args, pop @first_arg);
- $type = join " ", @first_arg;
-
- foreach $param (@args) {
- if ($param =~ m/^(\*+)\s*(.*)/) {
- save_struct_actual($2);
-
- push_parameter($2, "$type $1", $arg, $file, $declaration_name);
- } elsif ($param =~ m/(.*?):(\w+)/) {
- if ($type ne "") { # skip unnamed bit-fields
- save_struct_actual($1);
- push_parameter($1, "$type:$2", $arg, $file, $declaration_name)
- }
- } else {
- save_struct_actual($param);
- push_parameter($param, $type, $arg, $file, $declaration_name);
- }
- }
- }
- }
-}
-
-sub push_parameter($$$$$) {
- my $param = shift;
- my $type = shift;
- my $org_arg = shift;
- my $file = shift;
- my $declaration_name = shift;
-
- if (($anon_struct_union == 1) && ($type eq "") &&
- ($param eq "}")) {
- return; # ignore the ending }; from anon. struct/union
- }
-
- $anon_struct_union = 0;
- $param =~ s/[\[\)].*//;
-
- if ($type eq "" && $param =~ /\.\.\.$/)
- {
- if (!$param =~ /\w\.\.\.$/) {
- # handles unnamed variable parameters
- $param = "...";
- } elsif ($param =~ /\w\.\.\.$/) {
- # for named variable parameters of the form `x...`, remove the dots
- $param =~ s/\.\.\.$//;
- }
- if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
- $parameterdescs{$param} = "variable arguments";
- }
- }
- elsif ($type eq "" && ($param eq "" or $param eq "void"))
- {
- $param="void";
- $parameterdescs{void} = "no arguments";
- }
- elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
- # handle unnamed (anonymous) union or struct:
- {
- $type = $param;
- $param = "{unnamed_" . $param . "}";
- $parameterdescs{$param} = "anonymous\n";
- $anon_struct_union = 1;
- }
- elsif ($param =~ "__cacheline_group" )
- # handle cache group enforcing variables: they do not need be described in header files
- {
- return; # ignore __cacheline_group_begin and __cacheline_group_end
- }
-
- # warn if parameter has no description
- # (but ignore ones starting with # as these are not parameters
- # but inline preprocessor statements);
- # Note: It will also ignore void params and unnamed structs/unions
- if (!defined $parameterdescs{$param} && $param !~ /^#/) {
- $parameterdescs{$param} = $undescribed;
-
- if (show_warnings($type, $declaration_name) && $param !~ /\./) {
- emit_warning("${file}:$.", "Function parameter or struct member '$param' not described in '$declaration_name'\n");
- }
- }
-
- # strip spaces from $param so that it is one continuous string
- # on @parameterlist;
- # this fixes a problem where check_sections() cannot find
- # a parameter like "addr[6 + 2]" because it actually appears
- # as "addr[6", "+", "2]" on the parameter list;
- # but it's better to maintain the param string unchanged for output,
- # so just weaken the string compare in check_sections() to ignore
- # "[blah" in a parameter string;
- ###$param =~ s/\s*//g;
- push @parameterlist, $param;
- $org_arg =~ s/\s\s+/ /g;
- $parametertypes{$param} = $org_arg;
-}
-
-sub check_sections($$$$$) {
- my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck) = @_;
- my @sects = split ' ', $sectcheck;
- my @prms = split ' ', $prmscheck;
- my $err;
- my ($px, $sx);
- my $prm_clean; # strip trailing "[array size]" and/or beginning "*"
-
- foreach $sx (0 .. $#sects) {
- $err = 1;
- foreach $px (0 .. $#prms) {
- $prm_clean = $prms[$px];
- $prm_clean =~ s/\[.*\]//;
- $prm_clean =~ s/$attribute//i;
- # ignore array size in a parameter string;
- # however, the original param string may contain
- # spaces, e.g.: addr[6 + 2]
- # and this appears in @prms as "addr[6" since the
- # parameter list is split at spaces;
- # hence just ignore "[..." for the sections check;
- $prm_clean =~ s/\[.*//;
-
- ##$prm_clean =~ s/^\**//;
- if ($prm_clean eq $sects[$sx]) {
- $err = 0;
- last;
- }
- }
- if ($err) {
- if ($decl_type eq "function") {
- emit_warning("${file}:$.",
- "Excess function parameter " .
- "'$sects[$sx]' " .
- "description in '$decl_name'\n");
- } elsif (($decl_type eq "struct") or
- ($decl_type eq "union")) {
- emit_warning("${file}:$.",
- "Excess $decl_type member " .
- "'$sects[$sx]' " .
- "description in '$decl_name'\n");
- }
- }
- }
-}
-
-##
-# Checks the section describing the return value of a function.
-sub check_return_section {
- my $file = shift;
- my $declaration_name = shift;
- my $return_type = shift;
-
- # Ignore an empty return type (It's a macro)
- # Ignore functions with a "void" return type. (But don't ignore "void *")
- if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
- return;
- }
-
- if (!defined($sections{$section_return}) ||
- $sections{$section_return} eq "")
- {
- emit_warning("${file}:$.",
- "No description found for return value of " .
- "'$declaration_name'\n");
- }
-}
-
-##
-# takes a function prototype and the name of the current file being
-# processed and spits out all the details stored in the global
-# arrays/hashes.
-sub dump_function($$) {
- my $prototype = shift;
- my $file = shift;
- my $func_macro = 0;
-
- print_lineno($new_start_line);
-
- $prototype =~ s/^static +//;
- $prototype =~ s/^extern +//;
- $prototype =~ s/^asmlinkage +//;
- $prototype =~ s/^inline +//;
- $prototype =~ s/^__inline__ +//;
- $prototype =~ s/^__inline +//;
- $prototype =~ s/^__always_inline +//;
- $prototype =~ s/^noinline +//;
- $prototype =~ s/^__FORTIFY_INLINE +//;
- $prototype =~ s/__init +//;
- $prototype =~ s/__init_or_module +//;
- $prototype =~ s/__deprecated +//;
- $prototype =~ s/__flatten +//;
- $prototype =~ s/__meminit +//;
- $prototype =~ s/__must_check +//;
- $prototype =~ s/__weak +//;
- $prototype =~ s/__sched +//;
- $prototype =~ s/_noprof//;
- $prototype =~ s/__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +//;
- $prototype =~ s/__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +//;
- $prototype =~ s/__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +//;
- $prototype =~ s/DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)/$1, $2/;
- my $define = $prototype =~ s/^#\s*define\s+//; #ak added
- $prototype =~ s/__attribute_const__ +//;
- $prototype =~ s/__attribute__\s*\(\(
- (?:
- [\w\s]++ # attribute name
- (?:\([^)]*+\))? # attribute arguments
- \s*+,? # optional comma at the end
- )+
- \)\)\s+//x;
-
- # Yes, this truly is vile. We are looking for:
- # 1. Return type (may be nothing if we're looking at a macro)
- # 2. Function name
- # 3. Function parameters.
- #
- # All the while we have to watch out for function pointer parameters
- # (which IIRC is what the two sections are for), C types (these
- # regexps don't even start to express all the possibilities), and
- # so on.
- #
- # If you mess with these regexps, it's a good idea to check that
- # the following functions' documentation still comes out right:
- # - parport_register_device (function pointer parameters)
- # - atomic_set (macro)
- # - pci_match_device, __copy_to_user (long return type)
- my $name = qr{[a-zA-Z0-9_~:]+};
- my $prototype_end1 = qr{[^\(]*};
- my $prototype_end2 = qr{[^\{]*};
- my $prototype_end = qr{\(($prototype_end1|$prototype_end2)\)};
- my $type1 = qr{[\w\s]+};
- my $type2 = qr{$type1\*+};
-
- if ($define && $prototype =~ m/^()($name)\s+/) {
- # This is an object-like macro, it has no return type and no parameter
- # list.
- # Function-like macros are not allowed to have spaces between
- # declaration_name and opening parenthesis (notice the \s+).
- $return_type = $1;
- $declaration_name = $2;
- $func_macro = 1;
- } elsif ($prototype =~ m/^()($name)\s*$prototype_end/ ||
- $prototype =~ m/^($type1)\s+($name)\s*$prototype_end/ ||
- $prototype =~ m/^($type2+)\s*($name)\s*$prototype_end/) {
- $return_type = $1;
- $declaration_name = $2;
- my $args = $3;
-
- create_parameterlist($args, ',', $file, $declaration_name);
- } else {
- emit_warning("${file}:$.", "cannot understand function prototype: '$prototype'\n");
- return;
- }
-
- if ($identifier ne $declaration_name) {
- emit_warning("${file}:$.", "expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n");
- return;
- }
-
- my $prms = join " ", @parameterlist;
- check_sections($file, $declaration_name, "function", $sectcheck, $prms);
-
- # This check emits a lot of warnings at the moment, because many
- # functions don't have a 'Return' doc section. So until the number
- # of warnings goes sufficiently down, the check is only performed in
- # -Wreturn mode.
- # TODO: always perform the check.
- if ($Wreturn && !$func_macro) {
- check_return_section($file, $declaration_name, $return_type);
- }
-
- # The function parser can be called with a typedef parameter.
- # Handle it.
- if ($return_type =~ /typedef/) {
- output_declaration($declaration_name,
- 'function',
- {'function' => $declaration_name,
- 'typedef' => 1,
- 'module' => $modulename,
- 'functiontype' => $return_type,
- 'parameterlist' => \@parameterlist,
- 'parameterdescs' => \%parameterdescs,
- 'parametertypes' => \%parametertypes,
- 'sectionlist' => \@sectionlist,
- 'sections' => \%sections,
- 'purpose' => $declaration_purpose,
- 'func_macro' => $func_macro
- });
- } else {
- output_declaration($declaration_name,
- 'function',
- {'function' => $declaration_name,
- 'module' => $modulename,
- 'functiontype' => $return_type,
- 'parameterlist' => \@parameterlist,
- 'parameterdescs' => \%parameterdescs,
- 'parametertypes' => \%parametertypes,
- 'sectionlist' => \@sectionlist,
- 'sections' => \%sections,
- 'purpose' => $declaration_purpose,
- 'func_macro' => $func_macro
- });
- }
-}
-
-sub reset_state {
- $function = "";
- %parameterdescs = ();
- %parametertypes = ();
- @parameterlist = ();
- %sections = ();
- @sectionlist = ();
- $sectcheck = "";
- $struct_actual = "";
- $prototype = "";
-
- $state = STATE_NORMAL;
- $inline_doc_state = STATE_INLINE_NA;
-}
-
-sub tracepoint_munge($) {
- my $file = shift;
- my $tracepointname = 0;
- my $tracepointargs = 0;
-
- if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
- $tracepointname = $1;
- }
- if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
- $tracepointname = $1;
- }
- if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
- $tracepointname = $2;
- }
- $tracepointname =~ s/^\s+//; #strip leading whitespace
- if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
- $tracepointargs = $1;
- }
- if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
- emit_warning("${file}:$.", "Unrecognized tracepoint format: \n".
- "$prototype\n");
- } else {
- $prototype = "static inline void trace_$tracepointname($tracepointargs)";
- $identifier = "trace_$identifier";
- }
-}
-
-sub syscall_munge() {
- my $void = 0;
-
- $prototype =~ s@[\r\n]+@ @gos; # strip newlines/CR's
-## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
- if ($prototype =~ m/SYSCALL_DEFINE0/) {
- $void = 1;
-## $prototype = "long sys_$1(void)";
- }
-
- $prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
- if ($prototype =~ m/long (sys_.*?),/) {
- $prototype =~ s/,/\(/;
- } elsif ($void) {
- $prototype =~ s/\)/\(void\)/;
- }
-
- # now delete all of the odd-number commas in $prototype
- # so that arg types & arg names don't have a comma between them
- my $count = 0;
- my $len = length($prototype);
- if ($void) {
- $len = 0; # skip the for-loop
- }
- for (my $ix = 0; $ix < $len; $ix++) {
- if (substr($prototype, $ix, 1) eq ',') {
- $count++;
- if ($count % 2 == 1) {
- substr($prototype, $ix, 1) = ' ';
- }
- }
- }
-}
-
-sub process_proto_function($$) {
- my $x = shift;
- my $file = shift;
-
- $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
-
- if ($x =~ /^#/ && $x !~ /^#\s*define/) {
- # do nothing
- } elsif ($x =~ /([^\{]*)/) {
- $prototype .= $1;
- }
-
- if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
- $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
- $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
- $prototype =~ s@^\s+@@gos; # strip leading spaces
-
- # Handle prototypes for function pointers like:
- # int (*pcs_config)(struct foo)
- $prototype =~ s@^(\S+\s+)\(\s*\*(\S+)\)@$1$2@gos;
-
- if ($prototype =~ /SYSCALL_DEFINE/) {
- syscall_munge();
- }
- if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
- $prototype =~ /DEFINE_SINGLE_EVENT/)
- {
- tracepoint_munge($file);
- }
- dump_function($prototype, $file);
- reset_state();
- }
-}
-
-sub process_proto_type($$) {
- my $x = shift;
- my $file = shift;
-
- $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
- $x =~ s@^\s+@@gos; # strip leading spaces
- $x =~ s@\s+$@@gos; # strip trailing spaces
- $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
-
- if ($x =~ /^#/) {
- # To distinguish preprocessor directive from regular declaration later.
- $x .= ";";
- }
-
- while (1) {
- if ( $x =~ /([^\{\};]*)([\{\};])(.*)/ ) {
- if( length $prototype ) {
- $prototype .= " "
- }
- $prototype .= $1 . $2;
- ($2 eq '{') && $brcount++;
- ($2 eq '}') && $brcount--;
- if (($2 eq ';') && ($brcount == 0)) {
- dump_declaration($prototype, $file);
- reset_state();
- last;
- }
- $x = $3;
- } else {
- $prototype .= $x;
- last;
- }
- }
-}
-
-
-sub map_filename($) {
- my $file;
- my ($orig_file) = @_;
-
- if (defined($ENV{'SRCTREE'})) {
- $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
- } else {
- $file = $orig_file;
- }
-
- return $file;
-}
-
-sub process_export_file($) {
- my ($orig_file) = @_;
- my $file = map_filename($orig_file);
-
- if (!open(IN,"<$file")) {
- print STDERR "Error: Cannot open file $file\n";
- ++$errors;
- return;
- }
-
- while (<IN>) {
- if (/$export_symbol/) {
- next if (defined($nosymbol_table{$2}));
- $function_table{$2} = 1;
- }
- if (/$export_symbol_ns/) {
- next if (defined($nosymbol_table{$2}));
- $function_table{$2} = 1;
- }
- }
-
- close(IN);
-}
-
-#
-# Parsers for the various processing states.
-#
-# STATE_NORMAL: looking for the /** to begin everything.
-#
-sub process_normal() {
- if (/$doc_start/o) {
- $state = STATE_NAME; # next line is always the function name
- $declaration_start_line = $. + 1;
- }
-}
-
-#
-# STATE_NAME: Looking for the "name - description" line
-#
-sub process_name($$) {
- my $file = shift;
- my $descr;
-
- if (/$doc_block/o) {
- $state = STATE_DOCBLOCK;
- $contents = "";
- $new_start_line = $.;
-
- if ( $1 eq "" ) {
- $section = $section_intro;
- } else {
- $section = $1;
- }
- } elsif (/$doc_decl/o) {
- $identifier = $1;
- my $is_kernel_comment = 0;
- my $decl_start = qr{$doc_com};
- # test for pointer declaration type, foo * bar() - desc
- my $fn_type = qr{\w+\s*\*\s*};
- my $parenthesis = qr{\(\w*\)};
- my $decl_end = qr{[-:].*};
- if (/^$decl_start([\w\s]+?)$parenthesis?\s*$decl_end?$/) {
- $identifier = $1;
- }
- if ($identifier =~ m/^(struct|union|enum|typedef)\b\s*(\S*)/) {
- $decl_type = $1;
- $identifier = $2;
- $is_kernel_comment = 1;
- }
- # Look for foo() or static void foo() - description; or misspelt
- # identifier
- elsif (/^$decl_start$fn_type?(\w+)\s*$parenthesis?\s*$decl_end?$/ ||
- /^$decl_start$fn_type?(\w+[^-:]*)$parenthesis?\s*$decl_end$/) {
- $identifier = $1;
- $decl_type = 'function';
- $identifier =~ s/^define\s+//;
- $is_kernel_comment = 1;
- }
- $identifier =~ s/\s+$//;
-
- $state = STATE_BODY;
- # if there's no @param blocks need to set up default section
- # here
- $contents = "";
- $section = $section_default;
- $new_start_line = $. + 1;
- if (/[-:](.*)/) {
- # strip leading/trailing/multiple spaces
- $descr= $1;
- $descr =~ s/^\s*//;
- $descr =~ s/\s*$//;
- $descr =~ s/\s+/ /g;
- $declaration_purpose = $descr;
- $state = STATE_BODY_MAYBE;
- } else {
- $declaration_purpose = "";
- }
-
- if (!$is_kernel_comment) {
- emit_warning("${file}:$.", "This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n$_");
- $state = STATE_NORMAL;
- }
-
- if (($declaration_purpose eq "") && $Wshort_desc) {
- emit_warning("${file}:$.", "missing initial short description on line:\n$_");
- }
-
- if ($identifier eq "" && $decl_type ne "enum") {
- emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n$_");
- $state = STATE_NORMAL;
- }
-
- if ($verbose) {
- print STDERR "${file}:$.: info: Scanning doc for $decl_type $identifier\n";
- }
- } else {
- emit_warning("${file}:$.", "Cannot understand $_ on line $. - I thought it was a doc line\n");
- $state = STATE_NORMAL;
- }
-}
-
-
-#
-# STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment.
-#
-sub process_body($$) {
- my $file = shift;
-
- if ($state == STATE_BODY_WITH_BLANK_LINE && /^\s*\*\s?\S/) {
- dump_section($file, $section, $contents);
- $section = $section_default;
- $new_start_line = $.;
- $contents = "";
- }
-
- if (/$doc_sect/i) { # case insensitive for supported section names
- $newsection = $1;
- $newcontents = $2;
-
- # map the supported section names to the canonical names
- if ($newsection =~ m/^description$/i) {
- $newsection = $section_default;
- } elsif ($newsection =~ m/^context$/i) {
- $newsection = $section_context;
- } elsif ($newsection =~ m/^returns?$/i) {
- $newsection = $section_return;
- } elsif ($newsection =~ m/^\@return$/) {
- # special: @return is a section, not a param description
- $newsection = $section_return;
- }
-
- if (($contents ne "") && ($contents ne "\n")) {
- dump_section($file, $section, $contents);
- $section = $section_default;
- }
-
- $state = STATE_BODY;
- $contents = $newcontents;
- $new_start_line = $.;
- while (substr($contents, 0, 1) eq " ") {
- $contents = substr($contents, 1);
- }
- if ($contents ne "") {
- $contents .= "\n";
- }
- $section = $newsection;
- $leading_space = undef;
- } elsif (/$doc_end/) {
- if (($contents ne "") && ($contents ne "\n")) {
- dump_section($file, $section, $contents);
- $section = $section_default;
- $contents = "";
- }
- # look for doc_com + <text> + doc_end:
- if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
- emit_warning("${file}:$.", "suspicious ending line: $_");
- }
-
- $prototype = "";
- $state = STATE_PROTO;
- $brcount = 0;
- $new_start_line = $. + 1;
- } elsif (/$doc_content/) {
- if ($1 eq "") {
- if ($section eq $section_context) {
- dump_section($file, $section, $contents);
- $section = $section_default;
- $contents = "";
- $new_start_line = $.;
- $state = STATE_BODY;
- } else {
- if ($section ne $section_default) {
- $state = STATE_BODY_WITH_BLANK_LINE;
- } else {
- $state = STATE_BODY;
- }
- $contents .= "\n";
- }
- } elsif ($state == STATE_BODY_MAYBE) {
- # Continued declaration purpose
- chomp($declaration_purpose);
- $declaration_purpose .= " " . $1;
- $declaration_purpose =~ s/\s+/ /g;
- } else {
- my $cont = $1;
- if ($section =~ m/^@/ || $section eq $section_context) {
- if (!defined $leading_space) {
- if ($cont =~ m/^(\s+)/) {
- $leading_space = $1;
- } else {
- $leading_space = "";
- }
- }
- $cont =~ s/^$leading_space//;
- }
- $contents .= $cont . "\n";
- }
- } else {
- # i dont know - bad line? ignore.
- emit_warning("${file}:$.", "bad line: $_");
- }
-}
-
-
-#
-# STATE_PROTO: reading a function/whatever prototype.
-#
-sub process_proto($$) {
- my $file = shift;
-
- if (/$doc_inline_oneline/) {
- $section = $1;
- $contents = $2;
- if ($contents ne "") {
- $contents .= "\n";
- dump_section($file, $section, $contents);
- $section = $section_default;
- $contents = "";
- }
- } elsif (/$doc_inline_start/) {
- $state = STATE_INLINE;
- $inline_doc_state = STATE_INLINE_NAME;
- } elsif ($decl_type eq 'function') {
- process_proto_function($_, $file);
- } else {
- process_proto_type($_, $file);
- }
-}
-
-#
-# STATE_DOCBLOCK: within a DOC: block.
-#
-sub process_docblock($$) {
- my $file = shift;
-
- if (/$doc_end/) {
- dump_doc_section($file, $section, $contents);
- $section = $section_default;
- $contents = "";
- $function = "";
- %parameterdescs = ();
- %parametertypes = ();
- @parameterlist = ();
- %sections = ();
- @sectionlist = ();
- $prototype = "";
- $state = STATE_NORMAL;
- } elsif (/$doc_content/) {
- if ( $1 eq "" ) {
- $contents .= $blankline;
- } else {
- $contents .= $1 . "\n";
- }
- }
-}
-
-#
-# STATE_INLINE: docbook comments within a prototype.
-#
-sub process_inline($$) {
- my $file = shift;
-
- # First line (state 1) needs to be a @parameter
- if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
- $section = $1;
- $contents = $2;
- $new_start_line = $.;
- if ($contents ne "") {
- while (substr($contents, 0, 1) eq " ") {
- $contents = substr($contents, 1);
- }
- $contents .= "\n";
- }
- $inline_doc_state = STATE_INLINE_TEXT;
- # Documentation block end */
- } elsif (/$doc_inline_end/) {
- if (($contents ne "") && ($contents ne "\n")) {
- dump_section($file, $section, $contents);
- $section = $section_default;
- $contents = "";
- }
- $state = STATE_PROTO;
- $inline_doc_state = STATE_INLINE_NA;
- # Regular text
- } elsif (/$doc_content/) {
- if ($inline_doc_state == STATE_INLINE_TEXT) {
- $contents .= $1 . "\n";
- # nuke leading blank lines
- if ($contents =~ /^\s*$/) {
- $contents = "";
- }
- } elsif ($inline_doc_state == STATE_INLINE_NAME) {
- $inline_doc_state = STATE_INLINE_ERROR;
- emit_warning("${file}:$.", "Incorrect use of kernel-doc format: $_");
- }
- }
-}
-
-
-sub process_file($) {
- my $file;
- my ($orig_file) = @_;
-
- $file = map_filename($orig_file);
-
- if (!open(IN_FILE,"<$file")) {
- print STDERR "Error: Cannot open file $file\n";
- ++$errors;
- return;
- }
-
- $. = 1;
-
- $section_counter = 0;
- while (<IN_FILE>) {
- while (!/^ \*/ && s/\\\s*$//) {
- $_ .= <IN_FILE>;
- }
- # Replace tabs by spaces
- while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
- # Hand this line to the appropriate state handler
- if ($state == STATE_NORMAL) {
- process_normal();
- } elsif ($state == STATE_NAME) {
- process_name($file, $_);
- } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE ||
- $state == STATE_BODY_WITH_BLANK_LINE) {
- process_body($file, $_);
- } elsif ($state == STATE_INLINE) { # scanning for inline parameters
- process_inline($file, $_);
- } elsif ($state == STATE_PROTO) {
- process_proto($file, $_);
- } elsif ($state == STATE_DOCBLOCK) {
- process_docblock($file, $_);
- }
- }
-
- # Make sure we got something interesting.
- if (!$section_counter && $output_mode ne "none") {
- if ($output_selection == OUTPUT_INCLUDE) {
- emit_warning("${file}:1", "'$_' not found\n")
- for keys %function_table;
- } else {
- emit_warning("${file}:1", "no structured comments found\n");
- }
- }
- close IN_FILE;
-}
-
-$kernelversion = get_kernel_version();
-
-# generate a sequence of code that will splice in highlighting information
-# using the s// operator.
-for (my $k = 0; $k < @highlights; $k++) {
- my $pattern = $highlights[$k][0];
- my $result = $highlights[$k][1];
-# print STDERR "scanning pattern:$pattern, highlight:($result)\n";
- $dohighlight .= "\$contents =~ s:$pattern:$result:gs;\n";
-}
-
-if ($output_selection == OUTPUT_EXPORTED ||
- $output_selection == OUTPUT_INTERNAL) {
-
- push(@export_file_list, @ARGV);
-
- foreach (@export_file_list) {
- chomp;
- process_export_file($_);
- }
-}
-
-foreach (@ARGV) {
- chomp;
- process_file($_);
-}
-if ($verbose && $errors) {
- print STDERR "$errors errors\n";
-}
-if ($verbose && $warnings) {
- print STDERR "$warnings warnings\n";
-}
-
-if ($Werror && $warnings) {
- print STDERR "$warnings warnings as Errors\n";
- exit($warnings);
-} else {
- exit($output_mode eq "none" ? 0 : $errors)
-}
-
-__END__
-
-=head1 OPTIONS
-
-=head2 Output format selection (mutually exclusive):
-
-=over 8
-
-=item -man
-
-Output troff manual page format.
-
-=item -rst
-
-Output reStructuredText format. This is the default.
-
-=item -none
-
-Do not output documentation, only warnings.
-
-=back
-
-=head2 Output format modifiers
-
-=head3 reStructuredText only
-
-=head2 Output selection (mutually exclusive):
-
-=over 8
-
-=item -export
-
-Only output documentation for the symbols that have been exported using
-EXPORT_SYMBOL() and related macros in any input FILE or -export-file FILE.
-
-=item -internal
-
-Only output documentation for the symbols that have NOT been exported using
-EXPORT_SYMBOL() and related macros in any input FILE or -export-file FILE.
-
-=item -function NAME
-
-Only output documentation for the given function or DOC: section title.
-All other functions and DOC: sections are ignored.
-
-May be specified multiple times.
-
-=item -nosymbol NAME
-
-Exclude the specified symbol from the output documentation.
-
-May be specified multiple times.
-
-=back
-
-=head2 Output selection modifiers:
-
-=over 8
-
-=item -no-doc-sections
-
-Do not output DOC: sections.
-
-=item -export-file FILE
-
-Specify an additional FILE in which to look for EXPORT_SYMBOL information.
-
-To be used with -export or -internal.
-
-May be specified multiple times.
-
-=back
-
-=head3 reStructuredText only
-
-=over 8
-
-=item -enable-lineno
-
-Enable output of .. LINENO lines.
-
-=back
-
-=head2 Other parameters:
-
-=over 8
-
-=item -h, -help
-
-Print this help.
-
-=item -v
-
-Verbose output, more warnings and other information.
-
-=item -Werror
-
-Treat warnings as errors.
-
-=back
-
-=cut
--
2.50.1
^ permalink raw reply related [flat|nested] 47+ messages in thread
* Re: [PATCH RFC 00/13] Collect documention-related tools under tools/doc
2025-08-13 21:31 [PATCH RFC 00/13] Collect documention-related tools under tools/doc Jonathan Corbet
` (12 preceding siblings ...)
2025-08-13 21:32 ` [PATCH 13/13] docs: remove kernel-doc.pl Jonathan Corbet
@ 2025-08-13 21:38 ` Jonathan Corbet
2025-08-13 23:29 ` Mauro Carvalho Chehab
2025-08-14 14:59 ` Jani Nikula
15 siblings, 0 replies; 47+ messages in thread
From: Jonathan Corbet @ 2025-08-13 21:38 UTC (permalink / raw)
To: linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa, Randy Dunlap,
Alex Shi, Yanteng Si, Dongliang Mu
[Adding some CCs - sorry, folks, I messed that part up somehow...]
Jonathan Corbet <corbet@lwn.net> writes:
> Our documentation-related tools are spread out over various directories;
> several are buried in the scripts/ dumping ground. That makes them harder
> to discover and harder to maintain.
>
> Recently, the idea of creating a dedicated directory for documentation tools
> came up; I decided to see what it would look like. This series creates a
> new directory, tools/doc, and moves various utilities there, hopefully
> fixing up all of the relevant references in the process.
>
> At the end, rather than move the old, Perl kernel-doc, I simply removed it.
>
> The big elephant lurking in this small room is the home for Python modules;
> I left them under scripts/lib, but that is an even less appropriate place
> than it was before. I would propose either tools/python or lib/python;
> thoughts on that matter welcome.
>
>
> Jonathan Corbet (13):
> docs: Move the "features" tools to tools/doc
> docs: move checktransupdate.py to tools/doc
> docs: move scripts/check-variable-fonts.sh to tools/doc
> docs: move scripts/documentation-file-ref-check to tools/doc
> docs: move parallel-wrapper.sh to tools/doc/
> docs: move get_abi.py to tools/doc
> docs: move sphinx-pre-install to tools/doc
> docs: move test_doc_build.py to tools/doc
> docs: move parse-headers.pl to tools/doc
> docs: move kernel-doc to tools/doc
> docs: move split-man.pl to tools/doc
> docs: move find-unused-docs.sh to tools/doc
> docs: remove kernel-doc.pl
>
> Documentation/Kconfig | 2 +-
> Documentation/Makefile | 24 +-
> Documentation/conf.py | 2 +-
> Documentation/doc-guide/checktransupdate.rst | 6 +-
> Documentation/doc-guide/contributing.rst | 2 +-
> Documentation/doc-guide/kernel-doc.rst | 18 +-
> Documentation/doc-guide/parse-headers.rst | 6 +-
> Documentation/doc-guide/sphinx.rst | 6 +-
> Documentation/kbuild/kbuild.rst | 2 +-
> Documentation/process/coding-style.rst | 2 +-
> Documentation/sphinx/kernel_abi.py | 2 +-
> Documentation/sphinx/kernel_feat.py | 4 +-
> Documentation/sphinx/kerneldoc-preamble.sty | 2 +-
> .../it_IT/doc-guide/kernel-doc.rst | 8 +-
> .../it_IT/doc-guide/parse-headers.rst | 6 +-
> .../translations/it_IT/doc-guide/sphinx.rst | 4 +-
> .../sp_SP/process/coding-style.rst | 2 +-
> .../zh_CN/doc-guide/checktransupdate.rst | 6 +-
> .../zh_CN/doc-guide/contributing.rst | 2 +-
> .../zh_CN/doc-guide/kernel-doc.rst | 16 +-
> .../zh_CN/doc-guide/parse-headers.rst | 6 +-
> .../translations/zh_CN/doc-guide/sphinx.rst | 4 +-
> Documentation/translations/zh_CN/how-to.rst | 4 +-
> .../translations/zh_CN/kbuild/kbuild.rst | 2 +-
> .../zh_CN/process/coding-style.rst | 2 +-
> .../zh_TW/process/coding-style.rst | 2 +-
> Documentation/userspace-api/media/Makefile | 2 +-
> MAINTAINERS | 11 +-
> Makefile | 2 +-
> drivers/gpu/drm/i915/Makefile | 2 +-
> scripts/kernel-doc | 1 -
> scripts/kernel-doc.pl | 2439 -----------------
> .../doc}/check-variable-fonts.sh | 2 +-
> {scripts => tools/doc}/checktransupdate.py | 8 +-
> .../doc}/documentation-file-ref-check | 2 +-
> .../scripts => tools/doc}/features-refresh.sh | 0
> {scripts => tools/doc}/find-unused-docs.sh | 8 +-
> {scripts => tools/doc}/get_abi.py | 0
> {scripts => tools/doc}/get_feat.pl | 2 +-
> scripts/kernel-doc.py => tools/doc/kernel-doc | 0
> .../features => tools/doc}/list-arch.sh | 2 +-
> .../sphinx => tools/doc}/parallel-wrapper.sh | 0
> .../sphinx => tools/doc}/parse-headers.pl | 4 +-
> {scripts => tools/doc}/sphinx-pre-install | 2 +-
> {scripts => tools/doc}/split-man.pl | 0
> {scripts => tools/doc}/test_doc_build.py | 0
> 46 files changed, 91 insertions(+), 2538 deletions(-)
> delete mode 120000 scripts/kernel-doc
> delete mode 100755 scripts/kernel-doc.pl
> rename {scripts => tools/doc}/check-variable-fonts.sh (98%)
> rename {scripts => tools/doc}/checktransupdate.py (98%)
> rename {scripts => tools/doc}/documentation-file-ref-check (99%)
> rename {Documentation/features/scripts => tools/doc}/features-refresh.sh (100%)
> rename {scripts => tools/doc}/find-unused-docs.sh (79%)
> rename {scripts => tools/doc}/get_abi.py (100%)
> rename {scripts => tools/doc}/get_feat.pl (99%)
> rename scripts/kernel-doc.py => tools/doc/kernel-doc (100%)
> rename {Documentation/features => tools/doc}/list-arch.sh (83%)
> rename {Documentation/sphinx => tools/doc}/parallel-wrapper.sh (100%)
> rename {Documentation/sphinx => tools/doc}/parse-headers.pl (98%)
> rename {scripts => tools/doc}/sphinx-pre-install (99%)
> rename {scripts => tools/doc}/split-man.pl (100%)
> rename {scripts => tools/doc}/test_doc_build.py (100%)
>
> --
> 2.50.1
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH RFC 00/13] Collect documention-related tools under tools/doc
2025-08-13 21:31 [PATCH RFC 00/13] Collect documention-related tools under tools/doc Jonathan Corbet
` (13 preceding siblings ...)
2025-08-13 21:38 ` [PATCH RFC 00/13] Collect documention-related tools under tools/doc Jonathan Corbet
@ 2025-08-13 23:29 ` Mauro Carvalho Chehab
2025-08-14 14:59 ` Jani Nikula
15 siblings, 0 replies; 47+ messages in thread
From: Mauro Carvalho Chehab @ 2025-08-13 23:29 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Akira Yokosawa, Randy Dunlap
Em Wed, 13 Aug 2025 15:31:59 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> Our documentation-related tools are spread out over various directories;
> several are buried in the scripts/ dumping ground. That makes them harder
> to discover and harder to maintain.
>
> Recently, the idea of creating a dedicated directory for documentation tools
> came up; I decided to see what it would look like. This series creates a
> new directory, tools/doc, and moves various utilities there, hopefully
> fixing up all of the relevant references in the process.
I would prefer tools/docs ;-)
The rationale is that it is common to have patches for Documentation
described with "docs:" prefix. Anyway, I don't mind that much.
Btw, one of my pending patch series is creating a new *.py script over
tools/docs (moving a script from Documentation/sphinx) ;-)
>
> At the end, rather than move the old, Perl kernel-doc, I simply removed it.
>
> The big elephant lurking in this small room is the home for Python modules;
> I left them under scripts/lib, but that is an even less appropriate place
> than it was before.
Agreed.
> I would propose either tools/python or lib/python;
> thoughts on that matter welcome.
Wither way works for me.
> Jonathan Corbet (13):
> docs: Move the "features" tools to tools/doc
> docs: move checktransupdate.py to tools/doc
> docs: move scripts/check-variable-fonts.sh to tools/doc
> docs: move scripts/documentation-file-ref-check to tools/doc
> docs: move parallel-wrapper.sh to tools/doc/
> docs: move get_abi.py to tools/doc
> docs: move sphinx-pre-install to tools/doc
> docs: move test_doc_build.py to tools/doc
> docs: move parse-headers.pl to tools/doc
> docs: move kernel-doc to tools/doc
> docs: move split-man.pl to tools/doc
> docs: move find-unused-docs.sh to tools/doc
> docs: remove kernel-doc.pl
>
> Documentation/Kconfig | 2 +-
> Documentation/Makefile | 24 +-
> Documentation/conf.py | 2 +-
> Documentation/doc-guide/checktransupdate.rst | 6 +-
> Documentation/doc-guide/contributing.rst | 2 +-
> Documentation/doc-guide/kernel-doc.rst | 18 +-
> Documentation/doc-guide/parse-headers.rst | 6 +-
> Documentation/doc-guide/sphinx.rst | 6 +-
> Documentation/kbuild/kbuild.rst | 2 +-
> Documentation/process/coding-style.rst | 2 +-
> Documentation/sphinx/kernel_abi.py | 2 +-
> Documentation/sphinx/kernel_feat.py | 4 +-
> Documentation/sphinx/kerneldoc-preamble.sty | 2 +-
> .../it_IT/doc-guide/kernel-doc.rst | 8 +-
> .../it_IT/doc-guide/parse-headers.rst | 6 +-
> .../translations/it_IT/doc-guide/sphinx.rst | 4 +-
> .../sp_SP/process/coding-style.rst | 2 +-
> .../zh_CN/doc-guide/checktransupdate.rst | 6 +-
> .../zh_CN/doc-guide/contributing.rst | 2 +-
> .../zh_CN/doc-guide/kernel-doc.rst | 16 +-
> .../zh_CN/doc-guide/parse-headers.rst | 6 +-
> .../translations/zh_CN/doc-guide/sphinx.rst | 4 +-
> Documentation/translations/zh_CN/how-to.rst | 4 +-
> .../translations/zh_CN/kbuild/kbuild.rst | 2 +-
> .../zh_CN/process/coding-style.rst | 2 +-
> .../zh_TW/process/coding-style.rst | 2 +-
> Documentation/userspace-api/media/Makefile | 2 +-
> MAINTAINERS | 11 +-
> Makefile | 2 +-
> drivers/gpu/drm/i915/Makefile | 2 +-
> scripts/kernel-doc | 1 -
> scripts/kernel-doc.pl | 2439 -----------------
> .../doc}/check-variable-fonts.sh | 2 +-
> {scripts => tools/doc}/checktransupdate.py | 8 +-
> .../doc}/documentation-file-ref-check | 2 +-
> .../scripts => tools/doc}/features-refresh.sh | 0
> {scripts => tools/doc}/find-unused-docs.sh | 8 +-
> {scripts => tools/doc}/get_abi.py | 0
> {scripts => tools/doc}/get_feat.pl | 2 +-
> scripts/kernel-doc.py => tools/doc/kernel-doc | 0
> .../features => tools/doc}/list-arch.sh | 2 +-
> .../sphinx => tools/doc}/parallel-wrapper.sh | 0
> .../sphinx => tools/doc}/parse-headers.pl | 4 +-
> {scripts => tools/doc}/sphinx-pre-install | 2 +-
> {scripts => tools/doc}/split-man.pl | 0
> {scripts => tools/doc}/test_doc_build.py | 0
> 46 files changed, 91 insertions(+), 2538 deletions(-)
> delete mode 120000 scripts/kernel-doc
> delete mode 100755 scripts/kernel-doc.pl
> rename {scripts => tools/doc}/check-variable-fonts.sh (98%)
> rename {scripts => tools/doc}/checktransupdate.py (98%)
> rename {scripts => tools/doc}/documentation-file-ref-check (99%)
> rename {Documentation/features/scripts => tools/doc}/features-refresh.sh (100%)
> rename {scripts => tools/doc}/find-unused-docs.sh (79%)
> rename {scripts => tools/doc}/get_abi.py (100%)
> rename {scripts => tools/doc}/get_feat.pl (99%)
> rename scripts/kernel-doc.py => tools/doc/kernel-doc (100%)
> rename {Documentation/features => tools/doc}/list-arch.sh (83%)
> rename {Documentation/sphinx => tools/doc}/parallel-wrapper.sh (100%)
> rename {Documentation/sphinx => tools/doc}/parse-headers.pl (98%)
I prefer if you don't touch those two. I'm already handling them.
Basically, parallel-wrapper.sh will be decommissioned; parse-readers.pl
will become parse-headers.py (on my series, at tools/docs, but if you
opt to tools/doc, I'll update it.
> rename {scripts => tools/doc}/sphinx-pre-install (99%)
> rename {scripts => tools/doc}/split-man.pl (100%)
> rename {scripts => tools/doc}/test_doc_build.py (100%)
Thanks,
Mauro
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 05/13] docs: move parallel-wrapper.sh to tools/doc/
2025-08-13 21:32 ` [PATCH 05/13] docs: move parallel-wrapper.sh to tools/doc/ Jonathan Corbet
@ 2025-08-13 23:31 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 47+ messages in thread
From: Mauro Carvalho Chehab @ 2025-08-13 23:31 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Akira Yokosawa, Randy Dunlap
Em Wed, 13 Aug 2025 15:32:04 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> This little script was buried in Documentation/sphinx/; put it with the
> other documentation-related tools.
This will conflict with my series getting rid of it and touching Makefile.
I prefer if you don't merge this one.
>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
> Documentation/Makefile | 2 +-
> {Documentation/sphinx => tools/doc}/parallel-wrapper.sh | 0
> 2 files changed, 1 insertion(+), 1 deletion(-)
> rename {Documentation/sphinx => tools/doc}/parallel-wrapper.sh (100%)
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index f7b8342f9666..962c4fab94b0 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -91,7 +91,7 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
> PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \
> BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(src)/$5/$(SPHINX_CONF)) \
> $(PYTHON3) $(srctree)/scripts/jobserver-exec \
> - $(CONFIG_SHELL) $(srctree)/Documentation/sphinx/parallel-wrapper.sh \
> + $(CONFIG_SHELL) $(srctree)/tools/doc/parallel-wrapper.sh \
> $(SPHINXBUILD) \
> -b $2 \
> -c $(abspath $(src)) \
> diff --git a/Documentation/sphinx/parallel-wrapper.sh b/tools/doc/parallel-wrapper.sh
> similarity index 100%
> rename from Documentation/sphinx/parallel-wrapper.sh
> rename to tools/doc/parallel-wrapper.sh
Thanks,
Mauro
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 09/13] docs: move parse-headers.pl to tools/doc
2025-08-13 21:32 ` [PATCH 09/13] docs: move parse-headers.pl " Jonathan Corbet
@ 2025-08-13 23:32 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 47+ messages in thread
From: Mauro Carvalho Chehab @ 2025-08-13 23:32 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Akira Yokosawa, Randy Dunlap
Em Wed, 13 Aug 2025 15:32:08 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> Move the tool and fix all the references, including the numerous ones that
> said "parse_headers" instead of "parse-headers".
This will conflict with my series getting converting it to Python.
I prefer if you don't merge this one.
>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
> Documentation/doc-guide/parse-headers.rst | 6 +++---
> .../translations/it_IT/doc-guide/parse-headers.rst | 6 +++---
> .../translations/zh_CN/doc-guide/parse-headers.rst | 6 +++---
> Documentation/userspace-api/media/Makefile | 2 +-
> MAINTAINERS | 1 -
> {Documentation/sphinx => tools/doc}/parse-headers.pl | 4 ++--
> 6 files changed, 12 insertions(+), 13 deletions(-)
> rename {Documentation/sphinx => tools/doc}/parse-headers.pl (98%)
>
> diff --git a/Documentation/doc-guide/parse-headers.rst b/Documentation/doc-guide/parse-headers.rst
> index 204b025f1349..954cd81523a0 100644
> --- a/Documentation/doc-guide/parse-headers.rst
> +++ b/Documentation/doc-guide/parse-headers.rst
> @@ -15,14 +15,14 @@ about how to use it inside the Kernel tree.
>
> .. _parse_headers:
>
> -parse_headers.pl
> +parse-headers.pl
> ^^^^^^^^^^^^^^^^
>
> NAME
> ****
>
>
> -parse_headers.pl - parse a C file, in order to identify functions, structs,
> +parse-headers.pl - parse a C file, in order to identify functions, structs,
> enums and defines and create cross-references to a Sphinx book.
>
>
> @@ -30,7 +30,7 @@ SYNOPSIS
> ********
>
>
> -\ **parse_headers.pl**\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
> +\ **parse-headers.pl**\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
>
> Where <options> can be: --debug, --help or --usage.
>
> diff --git a/Documentation/translations/it_IT/doc-guide/parse-headers.rst b/Documentation/translations/it_IT/doc-guide/parse-headers.rst
> index 026a23e49767..45b6b6fc4fb5 100644
> --- a/Documentation/translations/it_IT/doc-guide/parse-headers.rst
> +++ b/Documentation/translations/it_IT/doc-guide/parse-headers.rst
> @@ -20,21 +20,21 @@ consultate ``Documentation/userspace-api/media/Makefile``.
>
> .. _it_parse_headers:
>
> -parse_headers.pl
> +parse-headers.pl
> ^^^^^^^^^^^^^^^^
>
> NOME
> ****
>
>
> -parse_headers.pl - analizza i file C al fine di identificare funzioni,
> +parse-headers.pl - analizza i file C al fine di identificare funzioni,
> strutture, enumerati e definizioni, e creare riferimenti per Sphinx
>
> SINTASSI
> ********
>
>
> -\ **parse_headers.pl**\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
> +\ **parse-headers.pl**\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
>
> Dove <options> può essere: --debug, --usage o --help.
>
> diff --git a/Documentation/translations/zh_CN/doc-guide/parse-headers.rst b/Documentation/translations/zh_CN/doc-guide/parse-headers.rst
> index a08819e904ed..22253fea5da1 100644
> --- a/Documentation/translations/zh_CN/doc-guide/parse-headers.rst
> +++ b/Documentation/translations/zh_CN/doc-guide/parse-headers.rst
> @@ -19,14 +19,14 @@ Sphinx将生成警告。这有助于保持用户空间API文档与内核更改
>
> .. _parse_headers_zh:
>
> -parse_headers.pl
> +parse-headers.pl
> ----------------
>
> 脚本名称
> ~~~~~~~~
>
>
> -parse_headers.pl——解析一个C文件，识别函数、结构体、枚举、定义并对Sphinx文档
> +parse-headers.pl——解析一个C文件，识别函数、结构体、枚举、定义并对Sphinx文档
> 创建交叉引用。
>
>
> @@ -34,7 +34,7 @@ parse_headers.pl——解析一个C文件，识别函数、结构体、枚举、
> ~~~~~~~~
>
>
> -\ **parse_headers.pl**\ [<选项>] <C文件> <输出文件> [<例外文件>]
> +\ **parse-headers.pl**\ [<选项>] <C文件> <输出文件> [<例外文件>]
>
> <选项> 可以是： --debug, --help 或 --usage 。
>
> diff --git a/Documentation/userspace-api/media/Makefile b/Documentation/userspace-api/media/Makefile
> index 3d8aaf5c253b..632798bca615 100644
> --- a/Documentation/userspace-api/media/Makefile
> +++ b/Documentation/userspace-api/media/Makefile
> @@ -3,7 +3,7 @@
> # Rules to convert a .h file to inline RST documentation
>
> SRC_DIR=$(srctree)/Documentation/userspace-api/media
> -PARSER = $(srctree)/Documentation/sphinx/parse-headers.pl
> +PARSER = $(srctree)/tools/doc/parse-headers.pl
> UAPI = $(srctree)/include/uapi/linux
> KAPI = $(srctree)/include/linux
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 2f1374130240..c2d2ce92bf79 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -7338,7 +7338,6 @@ DOCUMENTATION SCRIPTS
> M: Mauro Carvalho Chehab <mchehab@kernel.org>
> L: linux-doc@vger.kernel.org
> S: Maintained
> -F: Documentation/sphinx/parse-headers.pl
> F: tools/doc/
>
> DOCUMENTATION/ITALIAN
> diff --git a/Documentation/sphinx/parse-headers.pl b/tools/doc/parse-headers.pl
> similarity index 98%
> rename from Documentation/sphinx/parse-headers.pl
> rename to tools/doc/parse-headers.pl
> index 7b1458544e2e..47b90bf8c96d 100755
> --- a/Documentation/sphinx/parse-headers.pl
> +++ b/tools/doc/parse-headers.pl
> @@ -340,12 +340,12 @@ __END__
>
> =head1 NAME
>
> -parse_headers.pl - parse a C file, in order to identify functions, structs,
> +parse-headers.pl - parse a C file, in order to identify functions, structs,
> enums and defines and create cross-references to a Sphinx book.
>
> =head1 SYNOPSIS
>
> -B<parse_headers.pl> [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
> +B<parse-headers.pl> [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
>
> Where <options> can be: --debug, --help or --usage.
>
Thanks,
Mauro
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 13/13] docs: remove kernel-doc.pl
2025-08-13 21:32 ` [PATCH 13/13] docs: remove kernel-doc.pl Jonathan Corbet
@ 2025-08-13 23:33 ` Mauro Carvalho Chehab
2025-08-15 2:43 ` Randy Dunlap
1 sibling, 0 replies; 47+ messages in thread
From: Mauro Carvalho Chehab @ 2025-08-13 23:33 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Akira Yokosawa, Randy Dunlap
Em Wed, 13 Aug 2025 15:32:12 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> We've been using the Python version and nobody has missed this one. All
> credit goes to Mauro Carvalho Chehab for creating the replacement.
>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
> scripts/kernel-doc.pl | 2439 -----------------------------------------
> 1 file changed, 2439 deletions(-)
> delete mode 100755 scripts/kernel-doc.pl
>
> diff --git a/scripts/kernel-doc.pl b/scripts/kernel-doc.pl
> deleted file mode 100755
> index 5db23cbf4eb2..000000000000
> --- a/scripts/kernel-doc.pl
> +++ /dev/null
> @@ -1,2439 +0,0 @@
> -#!/usr/bin/env perl
> -# SPDX-License-Identifier: GPL-2.0
> -# vim: softtabstop=4
> -
> -use warnings;
> -use strict;
> -
> -## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
> -## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
> -## Copyright (C) 2001 Simon Huggins ##
> -## Copyright (C) 2005-2012 Randy Dunlap ##
> -## Copyright (C) 2012 Dan Luedtke ##
> -## ##
> -## #define enhancements by Armin Kuster <akuster@mvista.com> ##
> -## Copyright (c) 2000 MontaVista Software, Inc. ##
> -#
> -# Copyright (C) 2022 Tomasz Warniełło (POD)
> -
> -use Pod::Usage qw/pod2usage/;
> -
> -=head1 NAME
> -
> -kernel-doc - Print formatted kernel documentation to stdout
> -
> -=head1 SYNOPSIS
> -
> - kernel-doc [-h] [-v] [-Werror] [-Wall] [-Wreturn] [-Wshort-desc[ription]] [-Wcontents-before-sections]
> - [ -man |
> - -rst [-enable-lineno] |
> - -none
> - ]
> - [
> - -export |
> - -internal |
> - [-function NAME] ... |
> - [-nosymbol NAME] ...
> - ]
> - [-no-doc-sections]
> - [-export-file FILE] ...
> - FILE ...
> -
> -Run `kernel-doc -h` for details.
> -
> -=head1 DESCRIPTION
> -
> -Read C language source or header FILEs, extract embedded documentation comments,
> -and print formatted documentation to standard output.
> -
> -The documentation comments are identified by the "/**" opening comment mark.
> -
> -See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
> -
> -=cut
> -
> -# more perldoc at the end of the file
> -
> -## init lots of data
> -
> -my $errors = 0;
> -my $warnings = 0;
> -my $anon_struct_union = 0;
> -
> -# match expressions used to find embedded type information
> -my $type_constant = '\b``([^\`]+)``\b';
> -my $type_constant2 = '\%([-_*\w]+)';
> -my $type_func = '(\w+)\(\)';
> -my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
> -my $type_param_ref = '([\!~\*]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
> -my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params
> -my $type_fp_param2 = '\@(\w+->\S+)\(\)'; # Special RST handling for structs with func ptr params
> -my $type_env = '(\$\w+)';
> -my $type_enum = '\&(enum\s*([_\w]+))';
> -my $type_struct = '\&(struct\s*([_\w]+))';
> -my $type_typedef = '\&(typedef\s*([_\w]+))';
> -my $type_union = '\&(union\s*([_\w]+))';
> -my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
> -my $type_fallback = '\&([_\w]+)';
> -my $type_member_func = $type_member . '\(\)';
> -
> -# Output conversion substitutions.
> -# One for each output format
> -
> -# these are pretty rough
> -my @highlights_man = (
> - [$type_constant, "\$1"],
> - [$type_constant2, "\$1"],
> - [$type_func, "\\\\fB\$1\\\\fP"],
> - [$type_enum, "\\\\fI\$1\\\\fP"],
> - [$type_struct, "\\\\fI\$1\\\\fP"],
> - [$type_typedef, "\\\\fI\$1\\\\fP"],
> - [$type_union, "\\\\fI\$1\\\\fP"],
> - [$type_param, "\\\\fI\$1\\\\fP"],
> - [$type_param_ref, "\\\\fI\$1\$2\\\\fP"],
> - [$type_member, "\\\\fI\$1\$2\$3\\\\fP"],
> - [$type_fallback, "\\\\fI\$1\\\\fP"]
> - );
> -my $blankline_man = "";
> -
> -# rst-mode
> -my @highlights_rst = (
> - [$type_constant, "``\$1``"],
> - [$type_constant2, "``\$1``"],
> -
> - # Note: need to escape () to avoid func matching later
> - [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"],
> - [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
> - [$type_fp_param, "**\$1\\\\(\\\\)**"],
> - [$type_fp_param2, "**\$1\\\\(\\\\)**"],
> - [$type_func, "\$1()"],
> - [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],
> - [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],
> - [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"],
> - [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"],
> -
> - # in rst this can refer to any type
> - [$type_fallback, "\\:c\\:type\\:`\$1`"],
> - [$type_param_ref, "**\$1\$2**"]
> - );
> -my $blankline_rst = "\n";
> -
> -# read arguments
> -if ($#ARGV == -1) {
> - pod2usage(
> - -message => "No arguments!\n",
> - -exitval => 1,
> - -verbose => 99,
> - -sections => 'SYNOPSIS',
> - -output => \*STDERR,
> - );
> -}
> -
> -my $kernelversion;
> -
> -my $dohighlight = "";
> -
> -my $verbose = 0;
> -my $Werror = 0;
> -my $Wreturn = 0;
> -my $Wshort_desc = 0;
> -my $output_mode = "rst";
> -my $output_preformatted = 0;
> -my $no_doc_sections = 0;
> -my $enable_lineno = 0;
> -my @highlights = @highlights_rst;
> -my $blankline = $blankline_rst;
> -my $modulename = "Kernel API";
> -
> -use constant {
> - OUTPUT_ALL => 0, # output all symbols and doc sections
> - OUTPUT_INCLUDE => 1, # output only specified symbols
> - OUTPUT_EXPORTED => 2, # output exported symbols
> - OUTPUT_INTERNAL => 3, # output non-exported symbols
> -};
> -my $output_selection = OUTPUT_ALL;
> -my $show_not_found = 0; # No longer used
> -
> -my @export_file_list;
> -
> -my @build_time;
> -if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
> - (my $seconds = `date -d "${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
> - @build_time = gmtime($seconds);
> -} else {
> - @build_time = localtime;
> -}
> -
> -my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
> - 'July', 'August', 'September', 'October',
> - 'November', 'December')[$build_time[4]] .
> - " " . ($build_time[5]+1900);
> -
> -# Essentially these are globals.
> -# They probably want to be tidied up, made more localised or something.
> -# CAVEAT EMPTOR! Some of the others I localised may not want to be, which
> -# could cause "use of undefined value" or other bugs.
> -my ($function, %function_table, %parametertypes, $declaration_purpose);
> -my %nosymbol_table = ();
> -my $declaration_start_line;
> -my ($type, $declaration_name, $return_type);
> -my ($newsection, $newcontents, $prototype, $brcount);
> -
> -if (defined($ENV{'KBUILD_VERBOSE'}) && $ENV{'KBUILD_VERBOSE'} =~ '1') {
> - $verbose = 1;
> -}
> -
> -if (defined($ENV{'KCFLAGS'})) {
> - my $kcflags = "$ENV{'KCFLAGS'}";
> -
> - if ($kcflags =~ /(\s|^)-Werror(\s|$)/) {
> - $Werror = 1;
> - }
> -}
> -
> -# reading this variable is for backwards compat just in case
> -# someone was calling it with the variable from outside the
> -# kernel's build system
> -if (defined($ENV{'KDOC_WERROR'})) {
> - $Werror = "$ENV{'KDOC_WERROR'}";
> -}
> -# other environment variables are converted to command-line
> -# arguments in cmd_checkdoc in the build system
> -
> -# Generated docbook code is inserted in a template at a point where
> -# docbook v3.1 requires a non-zero sequence of RefEntry's; see:
> -# https://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
> -# We keep track of number of generated entries and generate a dummy
> -# if needs be to ensure the expanded template can be postprocessed
> -# into html.
> -my $section_counter = 0;
> -
> -my $lineprefix="";
> -
> -# Parser states
> -use constant {
> - STATE_NORMAL => 0, # normal code
> - STATE_NAME => 1, # looking for function name
> - STATE_BODY_MAYBE => 2, # body - or maybe more description
> - STATE_BODY => 3, # the body of the comment
> - STATE_BODY_WITH_BLANK_LINE => 4, # the body, which has a blank line
> - STATE_PROTO => 5, # scanning prototype
> - STATE_DOCBLOCK => 6, # documentation block
> - STATE_INLINE => 7, # gathering doc outside main block
> -};
> -my $state;
> -my $leading_space;
> -
> -# Inline documentation state
> -use constant {
> - STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE)
> - STATE_INLINE_NAME => 1, # looking for member name (@foo:)
> - STATE_INLINE_TEXT => 2, # looking for member documentation
> - STATE_INLINE_END => 3, # done
> - STATE_INLINE_ERROR => 4, # error - Comment without header was found.
> - # Spit a warning as it's not
> - # proper kernel-doc and ignore the rest.
> -};
> -my $inline_doc_state;
> -
> -#declaration types: can be
> -# 'function', 'struct', 'union', 'enum', 'typedef'
> -my $decl_type;
> -
> -# Name of the kernel-doc identifier for non-DOC markups
> -my $identifier;
> -
> -my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
> -my $doc_end = '\*/';
> -my $doc_com = '\s*\*\s*';
> -my $doc_com_body = '\s*\* ?';
> -my $doc_decl = $doc_com . '(\w+)';
> -# @params and a strictly limited set of supported section names
> -# Specifically:
> -# Match @word:
> -# @...:
> -# @{section-name}:
> -# while trying to not match literal block starts like "example::"
> -#
> -my $doc_sect = $doc_com .
> - '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:([^:].*)?$';
> -my $doc_content = $doc_com_body . '(.*)';
> -my $doc_block = $doc_com . 'DOC:\s*(.*)?';
> -my $doc_inline_start = '^\s*/\*\*\s*$';
> -my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
> -my $doc_inline_end = '^\s*\*/\s*$';
> -my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
> -my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
> -my $export_symbol_ns = '^\s*EXPORT_SYMBOL_NS(_GPL)?\s*\(\s*(\w+)\s*,\s*"\S+"\)\s*;';
> -my $function_pointer = qr{([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)};
> -my $attribute = qr{__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)}i;
> -
> -my %parameterdescs;
> -my %parameterdesc_start_lines;
> -my @parameterlist;
> -my %sections;
> -my @sectionlist;
> -my %section_start_lines;
> -my $sectcheck;
> -my $struct_actual;
> -
> -my $contents = "";
> -my $new_start_line = 0;
> -
> -# the canonical section names. see also $doc_sect above.
> -my $section_default = "Description"; # default section
> -my $section_intro = "Introduction";
> -my $section = $section_default;
> -my $section_context = "Context";
> -my $section_return = "Return";
> -
> -my $undescribed = "-- undescribed --";
> -
> -reset_state();
> -
> -while ($ARGV[0] =~ m/^--?(.*)/) {
> - my $cmd = $1;
> - shift @ARGV;
> - if ($cmd eq "man") {
> - $output_mode = "man";
> - @highlights = @highlights_man;
> - $blankline = $blankline_man;
> - } elsif ($cmd eq "rst") {
> - $output_mode = "rst";
> - @highlights = @highlights_rst;
> - $blankline = $blankline_rst;
> - } elsif ($cmd eq "none") {
> - $output_mode = "none";
> - } elsif ($cmd eq "module") { # not needed for XML, inherits from calling document
> - $modulename = shift @ARGV;
> - } elsif ($cmd eq "function") { # to only output specific functions
> - $output_selection = OUTPUT_INCLUDE;
> - $function = shift @ARGV;
> - $function_table{$function} = 1;
> - } elsif ($cmd eq "nosymbol") { # Exclude specific symbols
> - my $symbol = shift @ARGV;
> - $nosymbol_table{$symbol} = 1;
> - } elsif ($cmd eq "export") { # only exported symbols
> - $output_selection = OUTPUT_EXPORTED;
> - %function_table = ();
> - } elsif ($cmd eq "internal") { # only non-exported symbols
> - $output_selection = OUTPUT_INTERNAL;
> - %function_table = ();
> - } elsif ($cmd eq "export-file") {
> - my $file = shift @ARGV;
> - push(@export_file_list, $file);
> - } elsif ($cmd eq "v") {
> - $verbose = 1;
> - } elsif ($cmd eq "Werror") {
> - $Werror = 1;
> - } elsif ($cmd eq "Wreturn") {
> - $Wreturn = 1;
> - } elsif ($cmd eq "Wshort-desc" or $cmd eq "Wshort-description") {
> - $Wshort_desc = 1;
> - } elsif ($cmd eq "Wall") {
> - $Wreturn = 1;
> - $Wshort_desc = 1;
> - } elsif (($cmd eq "h") || ($cmd eq "help")) {
> - pod2usage(-exitval => 0, -verbose => 2);
> - } elsif ($cmd eq 'no-doc-sections') {
> - $no_doc_sections = 1;
> - } elsif ($cmd eq 'enable-lineno') {
> - $enable_lineno = 1;
> - } elsif ($cmd eq 'show-not-found') {
> - $show_not_found = 1; # A no-op but don't fail
> - } else {
> - # Unknown argument
> - pod2usage(
> - -message => "Argument unknown!\n",
> - -exitval => 1,
> - -verbose => 99,
> - -sections => 'SYNOPSIS',
> - -output => \*STDERR,
> - );
> - }
> - if ($#ARGV < 0){
> - pod2usage(
> - -message => "FILE argument missing\n",
> - -exitval => 1,
> - -verbose => 99,
> - -sections => 'SYNOPSIS',
> - -output => \*STDERR,
> - );
> - }
> -}
> -
> -# continue execution near EOF;
> -
> -sub findprog($)
> -{
> - foreach(split(/:/, $ENV{PATH})) {
> - return "$_/$_[0]" if(-x "$_/$_[0]");
> - }
> -}
> -
> -# get kernel version from env
> -sub get_kernel_version() {
> - my $version = 'unknown kernel version';
> -
> - if (defined($ENV{'KERNELVERSION'})) {
> - $version = $ENV{'KERNELVERSION'};
> - }
> - return $version;
> -}
> -
> -#
> -sub print_lineno {
> - my $lineno = shift;
> - if ($enable_lineno && defined($lineno)) {
> - print ".. LINENO " . $lineno . "\n";
> - }
> -}
> -
> -sub emit_warning {
> - my $location = shift;
> - my $msg = shift;
> - print STDERR "$location: warning: $msg";
> - ++$warnings;
> -}
> -##
> -# dumps section contents to arrays/hashes intended for that purpose.
> -#
> -sub dump_section {
> - my $file = shift;
> - my $name = shift;
> - my $contents = join "\n", @_;
> -
> - if ($name =~ m/$type_param/) {
> - $name = $1;
> - $parameterdescs{$name} = $contents;
> - $sectcheck = $sectcheck . $name . " ";
> - $parameterdesc_start_lines{$name} = $new_start_line;
> - $new_start_line = 0;
> - } elsif ($name eq "@\.\.\.") {
> - $name = "...";
> - $parameterdescs{$name} = $contents;
> - $sectcheck = $sectcheck . $name . " ";
> - $parameterdesc_start_lines{$name} = $new_start_line;
> - $new_start_line = 0;
> - } else {
> - if (defined($sections{$name}) && ($sections{$name} ne "")) {
> - # Only warn on user specified duplicate section names.
> - if ($name ne $section_default) {
> - emit_warning("${file}:$.", "duplicate section name '$name'\n");
> - }
> - $sections{$name} .= $contents;
> - } else {
> - $sections{$name} = $contents;
> - push @sectionlist, $name;
> - $section_start_lines{$name} = $new_start_line;
> - $new_start_line = 0;
> - }
> - }
> -}
> -
> -##
> -# dump DOC: section after checking that it should go out
> -#
> -sub dump_doc_section {
> - my $file = shift;
> - my $name = shift;
> - my $contents = join "\n", @_;
> -
> - if ($no_doc_sections) {
> - return;
> - }
> -
> - return if (defined($nosymbol_table{$name}));
> -
> - if (($output_selection == OUTPUT_ALL) ||
> - (($output_selection == OUTPUT_INCLUDE) &&
> - defined($function_table{$name})))
> - {
> - dump_section($file, $name, $contents);
> - output_blockhead({'sectionlist' => \@sectionlist,
> - 'sections' => \%sections,
> - 'module' => $modulename,
> - 'content-only' => ($output_selection != OUTPUT_ALL), });
> - }
> -}
> -
> -##
> -# output function
> -#
> -# parameterdescs, a hash.
> -# function => "function name"
> -# parameterlist => @list of parameters
> -# parameterdescs => %parameter descriptions
> -# sectionlist => @list of sections
> -# sections => %section descriptions
> -#
> -
> -sub output_highlight {
> - my $contents = join "\n",@_;
> - my $line;
> -
> -# DEBUG
> -# if (!defined $contents) {
> -# use Carp;
> -# confess "output_highlight got called with no args?\n";
> -# }
> -
> -# print STDERR "contents b4:$contents\n";
> - eval $dohighlight;
> - die $@ if $@;
> -# print STDERR "contents af:$contents\n";
> -
> - foreach $line (split "\n", $contents) {
> - if (! $output_preformatted) {
> - $line =~ s/^\s*//;
> - }
> - if ($line eq ""){
> - if (! $output_preformatted) {
> - print $lineprefix, $blankline;
> - }
> - } else {
> - if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
> - print "\\&$line";
> - } else {
> - print $lineprefix, $line;
> - }
> - }
> - print "\n";
> - }
> -}
> -
> -##
> -# output function in man
> -sub output_function_man(%) {
> - my %args = %{$_[0]};
> - my ($parameter, $section);
> - my $count;
> - my $func_macro = $args{'func_macro'};
> - my $paramcount = $#{$args{'parameterlist'}}; # -1 is empty
> -
> - print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
> -
> - print ".SH NAME\n";
> - print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
> -
> - print ".SH SYNOPSIS\n";
> - if ($args{'functiontype'} ne "") {
> - print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
> - } else {
> - print ".B \"" . $args{'function'} . "\n";
> - }
> - $count = 0;
> - my $parenth = "(";
> - my $post = ",";
> - foreach my $parameter (@{$args{'parameterlist'}}) {
> - if ($count == $#{$args{'parameterlist'}}) {
> - $post = ");";
> - }
> - $type = $args{'parametertypes'}{$parameter};
> - if ($type =~ m/$function_pointer/) {
> - # pointer-to-function
> - print ".BI \"" . $parenth . $1 . "\" " . " \") (" . $2 . ")" . $post . "\"\n";
> - } else {
> - $type =~ s/([^\*])$/$1 /;
> - print ".BI \"" . $parenth . $type . "\" " . " \"" . $post . "\"\n";
> - }
> - $count++;
> - $parenth = "";
> - }
> -
> - $paramcount = $#{$args{'parameterlist'}}; # -1 is empty
> - if ($paramcount >= 0) {
> - print ".SH ARGUMENTS\n";
> - }
> - foreach $parameter (@{$args{'parameterlist'}}) {
> - my $parameter_name = $parameter;
> - $parameter_name =~ s/\[.*//;
> -
> - print ".IP \"" . $parameter . "\" 12\n";
> - output_highlight($args{'parameterdescs'}{$parameter_name});
> - }
> - foreach $section (@{$args{'sectionlist'}}) {
> - print ".SH \"", uc $section, "\"\n";
> - output_highlight($args{'sections'}{$section});
> - }
> -}
> -
> -##
> -# output enum in man
> -sub output_enum_man(%) {
> - my %args = %{$_[0]};
> - my ($parameter, $section);
> - my $count;
> -
> - print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
> -
> - print ".SH NAME\n";
> - print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
> -
> - print ".SH SYNOPSIS\n";
> - print "enum " . $args{'enum'} . " {\n";
> - $count = 0;
> - foreach my $parameter (@{$args{'parameterlist'}}) {
> - print ".br\n.BI \" $parameter\"\n";
> - if ($count == $#{$args{'parameterlist'}}) {
> - print "\n};\n";
> - last;
> - } else {
> - print ", \n.br\n";
> - }
> - $count++;
> - }
> -
> - print ".SH Constants\n";
> - foreach $parameter (@{$args{'parameterlist'}}) {
> - my $parameter_name = $parameter;
> - $parameter_name =~ s/\[.*//;
> -
> - print ".IP \"" . $parameter . "\" 12\n";
> - output_highlight($args{'parameterdescs'}{$parameter_name});
> - }
> - foreach $section (@{$args{'sectionlist'}}) {
> - print ".SH \"$section\"\n";
> - output_highlight($args{'sections'}{$section});
> - }
> -}
> -
> -##
> -# output struct in man
> -sub output_struct_man(%) {
> - my %args = %{$_[0]};
> - my ($parameter, $section);
> -
> - print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";
> -
> - print ".SH NAME\n";
> - print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
> -
> - my $declaration = $args{'definition'};
> - $declaration =~ s/\t/ /g;
> - $declaration =~ s/\n/"\n.br\n.BI \"/g;
> - print ".SH SYNOPSIS\n";
> - print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
> - print ".BI \"$declaration\n};\n.br\n\n";
> -
> - print ".SH Members\n";
> - foreach $parameter (@{$args{'parameterlist'}}) {
> - ($parameter =~ /^#/) && next;
> -
> - my $parameter_name = $parameter;
> - $parameter_name =~ s/\[.*//;
> -
> - ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
> - print ".IP \"" . $parameter . "\" 12\n";
> - output_highlight($args{'parameterdescs'}{$parameter_name});
> - }
> - foreach $section (@{$args{'sectionlist'}}) {
> - print ".SH \"$section\"\n";
> - output_highlight($args{'sections'}{$section});
> - }
> -}
> -
> -##
> -# output typedef in man
> -sub output_typedef_man(%) {
> - my %args = %{$_[0]};
> - my ($parameter, $section);
> -
> - print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
> -
> - print ".SH NAME\n";
> - print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
> -
> - foreach $section (@{$args{'sectionlist'}}) {
> - print ".SH \"$section\"\n";
> - output_highlight($args{'sections'}{$section});
> - }
> -}
> -
> -sub output_blockhead_man(%) {
> - my %args = %{$_[0]};
> - my ($parameter, $section);
> - my $count;
> -
> - print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
> -
> - foreach $section (@{$args{'sectionlist'}}) {
> - print ".SH \"$section\"\n";
> - output_highlight($args{'sections'}{$section});
> - }
> -}
> -
> -##
> -# output in restructured text
> -#
> -
> -#
> -# This could use some work; it's used to output the DOC: sections, and
> -# starts by putting out the name of the doc section itself, but that tends
> -# to duplicate a header already in the template file.
> -#
> -sub output_blockhead_rst(%) {
> - my %args = %{$_[0]};
> - my ($parameter, $section);
> -
> - foreach $section (@{$args{'sectionlist'}}) {
> - next if (defined($nosymbol_table{$section}));
> -
> - if ($output_selection != OUTPUT_INCLUDE) {
> - print ".. _$section:\n\n";
> - print "**$section**\n\n";
> - }
> - print_lineno($section_start_lines{$section});
> - output_highlight_rst($args{'sections'}{$section});
> - print "\n";
> - }
> -}
> -
> -#
> -# Apply the RST highlights to a sub-block of text.
> -#
> -sub highlight_block($) {
> - # The dohighlight kludge requires the text be called $contents
> - my $contents = shift;
> - eval $dohighlight;
> - die $@ if $@;
> - return $contents;
> -}
> -
> -#
> -# Regexes used only here.
> -#
> -my $sphinx_literal = '^[^.].*::$';
> -my $sphinx_cblock = '^\.\.\ +code-block::';
> -
> -sub output_highlight_rst {
> - my $input = join "\n",@_;
> - my $output = "";
> - my $line;
> - my $in_literal = 0;
> - my $litprefix;
> - my $block = "";
> -
> - foreach $line (split "\n",$input) {
> - #
> - # If we're in a literal block, see if we should drop out
> - # of it. Otherwise pass the line straight through unmunged.
> - #
> - if ($in_literal) {
> - if (! ($line =~ /^\s*$/)) {
> - #
> - # If this is the first non-blank line in a literal
> - # block we need to figure out what the proper indent is.
> - #
> - if ($litprefix eq "") {
> - $line =~ /^(\s*)/;
> - $litprefix = '^' . $1;
> - $output .= $line . "\n";
> - } elsif (! ($line =~ /$litprefix/)) {
> - $in_literal = 0;
> - } else {
> - $output .= $line . "\n";
> - }
> - } else {
> - $output .= $line . "\n";
> - }
> - }
> - #
> - # Not in a literal block (or just dropped out)
> - #
> - if (! $in_literal) {
> - $block .= $line . "\n";
> - if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) {
> - $in_literal = 1;
> - $litprefix = "";
> - $output .= highlight_block($block);
> - $block = ""
> - }
> - }
> - }
> -
> - if ($block) {
> - $output .= highlight_block($block);
> - }
> -
> - $output =~ s/^\n+//g;
> - $output =~ s/\n+$//g;
> -
> - foreach $line (split "\n", $output) {
> - print $lineprefix . $line . "\n";
> - }
> -}
> -
> -sub output_function_rst(%) {
> - my %args = %{$_[0]};
> - my ($parameter, $section);
> - my $oldprefix = $lineprefix;
> -
> - my $signature = "";
> - my $func_macro = $args{'func_macro'};
> - my $paramcount = $#{$args{'parameterlist'}}; # -1 is empty
> -
> - if ($func_macro) {
> - $signature = $args{'function'};
> - } else {
> - if ($args{'functiontype'}) {
> - $signature = $args{'functiontype'} . " ";
> - }
> - $signature .= $args{'function'} . " (";
> - }
> -
> - my $count = 0;
> - foreach my $parameter (@{$args{'parameterlist'}}) {
> - if ($count ne 0) {
> - $signature .= ", ";
> - }
> - $count++;
> - $type = $args{'parametertypes'}{$parameter};
> -
> - if ($type =~ m/$function_pointer/) {
> - # pointer-to-function
> - $signature .= $1 . $parameter . ") (" . $2 . ")";
> - } else {
> - $signature .= $type;
> - }
> - }
> -
> - if (!$func_macro) {
> - $signature .= ")";
> - }
> -
> - if ($args{'typedef'} || $args{'functiontype'} eq "") {
> - print ".. c:macro:: ". $args{'function'} . "\n\n";
> -
> - if ($args{'typedef'}) {
> - print_lineno($declaration_start_line);
> - print " **Typedef**: ";
> - $lineprefix = "";
> - output_highlight_rst($args{'purpose'});
> - print "\n\n**Syntax**\n\n";
> - print " ``$signature``\n\n";
> - } else {
> - print "``$signature``\n\n";
> - }
> - } else {
> - print ".. c:function:: $signature\n\n";
> - }
> -
> - if (!$args{'typedef'}) {
> - print_lineno($declaration_start_line);
> - $lineprefix = " ";
> - output_highlight_rst($args{'purpose'});
> - print "\n";
> - }
> -
> - #
> - # Put our descriptive text into a container (thus an HTML <div>) to help
> - # set the function prototypes apart.
> - #
> - $lineprefix = " ";
> - if ($paramcount >= 0) {
> - print ".. container:: kernelindent\n\n";
> - print $lineprefix . "**Parameters**\n\n";
> - }
> - foreach $parameter (@{$args{'parameterlist'}}) {
> - my $parameter_name = $parameter;
> - $parameter_name =~ s/\[.*//;
> - $type = $args{'parametertypes'}{$parameter};
> -
> - if ($type ne "") {
> - print $lineprefix . "``$type``\n";
> - } else {
> - print $lineprefix . "``$parameter``\n";
> - }
> -
> - print_lineno($parameterdesc_start_lines{$parameter_name});
> -
> - $lineprefix = " ";
> - if (defined($args{'parameterdescs'}{$parameter_name}) &&
> - $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
> - output_highlight_rst($args{'parameterdescs'}{$parameter_name});
> - } else {
> - print $lineprefix . "*undescribed*\n";
> - }
> - $lineprefix = " ";
> - print "\n";
> - }
> -
> - output_section_rst(@_);
> - $lineprefix = $oldprefix;
> -}
> -
> -sub output_section_rst(%) {
> - my %args = %{$_[0]};
> - my $section;
> - my $oldprefix = $lineprefix;
> -
> - foreach $section (@{$args{'sectionlist'}}) {
> - print $lineprefix . "**$section**\n\n";
> - print_lineno($section_start_lines{$section});
> - output_highlight_rst($args{'sections'}{$section});
> - print "\n";
> - }
> - print "\n";
> -}
> -
> -sub output_enum_rst(%) {
> - my %args = %{$_[0]};
> - my ($parameter);
> - my $oldprefix = $lineprefix;
> - my $count;
> - my $outer;
> -
> - my $name = $args{'enum'};
> - print "\n\n.. c:enum:: " . $name . "\n\n";
> -
> - print_lineno($declaration_start_line);
> - $lineprefix = " ";
> - output_highlight_rst($args{'purpose'});
> - print "\n";
> -
> - print ".. container:: kernelindent\n\n";
> - $outer = $lineprefix . " ";
> - $lineprefix = $outer . " ";
> - print $outer . "**Constants**\n\n";
> - foreach $parameter (@{$args{'parameterlist'}}) {
> - print $outer . "``$parameter``\n";
> -
> - if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
> - output_highlight_rst($args{'parameterdescs'}{$parameter});
> - } else {
> - print $lineprefix . "*undescribed*\n";
> - }
> - print "\n";
> - }
> - print "\n";
> - $lineprefix = $oldprefix;
> - output_section_rst(@_);
> -}
> -
> -sub output_typedef_rst(%) {
> - my %args = %{$_[0]};
> - my ($parameter);
> - my $oldprefix = $lineprefix;
> - my $name;
> -
> - $name = $args{'typedef'};
> -
> - print "\n\n.. c:type:: " . $name . "\n\n";
> - print_lineno($declaration_start_line);
> - $lineprefix = " ";
> - output_highlight_rst($args{'purpose'});
> - print "\n";
> -
> - $lineprefix = $oldprefix;
> - output_section_rst(@_);
> -}
> -
> -sub output_struct_rst(%) {
> - my %args = %{$_[0]};
> - my ($parameter);
> - my $oldprefix = $lineprefix;
> -
> - my $name = $args{'struct'};
> - if ($args{'type'} eq 'union') {
> - print "\n\n.. c:union:: " . $name . "\n\n";
> - } else {
> - print "\n\n.. c:struct:: " . $name . "\n\n";
> - }
> -
> - print_lineno($declaration_start_line);
> - $lineprefix = " ";
> - output_highlight_rst($args{'purpose'});
> - print "\n";
> -
> - print ".. container:: kernelindent\n\n";
> - print $lineprefix . "**Definition**::\n\n";
> - my $declaration = $args{'definition'};
> - $lineprefix = $lineprefix . " ";
> - $declaration =~ s/\t/$lineprefix/g;
> - print $lineprefix . $args{'type'} . " " . $args{'struct'} . " {\n$declaration" . $lineprefix . "};\n\n";
> -
> - $lineprefix = " ";
> - print $lineprefix . "**Members**\n\n";
> - foreach $parameter (@{$args{'parameterlist'}}) {
> - ($parameter =~ /^#/) && next;
> -
> - my $parameter_name = $parameter;
> - $parameter_name =~ s/\[.*//;
> -
> - ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
> - $type = $args{'parametertypes'}{$parameter};
> - print_lineno($parameterdesc_start_lines{$parameter_name});
> - print $lineprefix . "``" . $parameter . "``\n";
> - $lineprefix = " ";
> - output_highlight_rst($args{'parameterdescs'}{$parameter_name});
> - $lineprefix = " ";
> - print "\n";
> - }
> - print "\n";
> -
> - $lineprefix = $oldprefix;
> - output_section_rst(@_);
> -}
> -
> -## none mode output functions
> -
> -sub output_function_none(%) {
> -}
> -
> -sub output_enum_none(%) {
> -}
> -
> -sub output_typedef_none(%) {
> -}
> -
> -sub output_struct_none(%) {
> -}
> -
> -sub output_blockhead_none(%) {
> -}
> -
> -##
> -# generic output function for all types (function, struct/union, typedef, enum);
> -# calls the generated, variable output_ function name based on
> -# functype and output_mode
> -sub output_declaration {
> - no strict 'refs';
> - my $name = shift;
> - my $functype = shift;
> - my $func = "output_${functype}_$output_mode";
> -
> - return if (defined($nosymbol_table{$name}));
> -
> - if (($output_selection == OUTPUT_ALL) ||
> - (($output_selection == OUTPUT_INCLUDE ||
> - $output_selection == OUTPUT_EXPORTED) &&
> - defined($function_table{$name})) ||
> - ($output_selection == OUTPUT_INTERNAL &&
> - !($functype eq "function" && defined($function_table{$name}))))
> - {
> - &$func(@_);
> - $section_counter++;
> - }
> -}
> -
> -##
> -# generic output function - calls the right one based on current output mode.
> -sub output_blockhead {
> - no strict 'refs';
> - my $func = "output_blockhead_" . $output_mode;
> - &$func(@_);
> - $section_counter++;
> -}
> -
> -##
> -# takes a declaration (struct, union, enum, typedef) and
> -# invokes the right handler. NOT called for functions.
> -sub dump_declaration($$) {
> - no strict 'refs';
> - my ($prototype, $file) = @_;
> - my $func = "dump_" . $decl_type;
> - &$func(@_);
> -}
> -
> -sub dump_union($$) {
> - dump_struct(@_);
> -}
> -
> -sub dump_struct($$) {
> - my $x = shift;
> - my $file = shift;
> - my $decl_type;
> - my $members;
> - my $type = qr{struct|union};
> - # For capturing struct/union definition body, i.e. "{members*}qualifiers*"
> - my $qualifiers = qr{$attribute|__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned};
> - my $definition_body = qr{\{(.*)\}\s*$qualifiers*};
> - my $struct_members = qr{($type)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;};
> -
> - if ($x =~ /($type)\s+(\w+)\s*$definition_body/) {
> - $decl_type = $1;
> - $declaration_name = $2;
> - $members = $3;
> - } elsif ($x =~ /typedef\s+($type)\s*$definition_body\s*(\w+)\s*;/) {
> - $decl_type = $1;
> - $declaration_name = $3;
> - $members = $2;
> - }
> -
> - if ($members) {
> - if ($identifier ne $declaration_name) {
> - emit_warning("${file}:$.", "expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n");
> - return;
> - }
> -
> - # ignore members marked private:
> - $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
> - $members =~ s/\/\*\s*private:.*//gosi;
> - # strip comments:
> - $members =~ s/\/\*.*?\*\///gos;
> - # strip attributes
> - $members =~ s/\s*$attribute/ /gi;
> - $members =~ s/\s*__aligned\s*\([^;]*\)/ /gos;
> - $members =~ s/\s*__counted_by\s*\([^;]*\)/ /gos;
> - $members =~ s/\s*__counted_by_(le|be)\s*\([^;]*\)/ /gos;
> - $members =~ s/\s*__packed\s*/ /gos;
> - $members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos;
> - $members =~ s/\s*____cacheline_aligned_in_smp/ /gos;
> - $members =~ s/\s*____cacheline_aligned/ /gos;
> - # unwrap struct_group():
> - # - first eat non-declaration parameters and rewrite for final match
> - # - then remove macro, outer parens, and trailing semicolon
> - $members =~ s/\bstruct_group\s*\(([^,]*,)/STRUCT_GROUP(/gos;
> - $members =~ s/\bstruct_group_attr\s*\(([^,]*,){2}/STRUCT_GROUP(/gos;
> - $members =~ s/\bstruct_group_tagged\s*\(([^,]*),([^,]*),/struct $1 $2; STRUCT_GROUP(/gos;
> - $members =~ s/\b__struct_group\s*\(([^,]*,){3}/STRUCT_GROUP(/gos;
> - $members =~ s/\bSTRUCT_GROUP(\(((?:(?>[^)(]+)|(?1))*)\))[^;]*;/$2/gos;
> -
> - my $args = qr{([^,)]+)};
> - # replace DECLARE_BITMAP
> - $members =~ s/__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)/DECLARE_BITMAP($1, __ETHTOOL_LINK_MODE_MASK_NBITS)/gos;
> - $members =~ s/DECLARE_PHY_INTERFACE_MASK\s*\(([^\)]+)\)/DECLARE_BITMAP($1, PHY_INTERFACE_MODE_MAX)/gos;
> - $members =~ s/DECLARE_BITMAP\s*\($args,\s*$args\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
> - # replace DECLARE_HASHTABLE
> - $members =~ s/DECLARE_HASHTABLE\s*\($args,\s*$args\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
> - # replace DECLARE_KFIFO
> - $members =~ s/DECLARE_KFIFO\s*\($args,\s*$args,\s*$args\)/$2 \*$1/gos;
> - # replace DECLARE_KFIFO_PTR
> - $members =~ s/DECLARE_KFIFO_PTR\s*\($args,\s*$args\)/$2 \*$1/gos;
> - # replace DECLARE_FLEX_ARRAY
> - $members =~ s/(?:__)?DECLARE_FLEX_ARRAY\s*\($args,\s*$args\)/$1 $2\[\]/gos;
> - #replace DEFINE_DMA_UNMAP_ADDR
> - $members =~ s/DEFINE_DMA_UNMAP_ADDR\s*\($args\)/dma_addr_t $1/gos;
> - #replace DEFINE_DMA_UNMAP_LEN
> - $members =~ s/DEFINE_DMA_UNMAP_LEN\s*\($args\)/__u32 $1/gos;
> - my $declaration = $members;
> -
> - # Split nested struct/union elements as newer ones
> - while ($members =~ m/$struct_members/) {
> - my $newmember;
> - my $maintype = $1;
> - my $ids = $4;
> - my $content = $3;
> - foreach my $id(split /,/, $ids) {
> - $newmember .= "$maintype $id; ";
> -
> - $id =~ s/[:\[].*//;
> - $id =~ s/^\s*\**(\S+)\s*/$1/;
> - foreach my $arg (split /;/, $content) {
> - next if ($arg =~ m/^\s*$/);
> - if ($arg =~ m/^([^\(]+\(\*?\s*)([\w\.]*)(\s*\).*)/) {
> - # pointer-to-function
> - my $type = $1;
> - my $name = $2;
> - my $extra = $3;
> - next if (!$name);
> - if ($id =~ m/^\s*$/) {
> - # anonymous struct/union
> - $newmember .= "$type$name$extra; ";
> - } else {
> - $newmember .= "$type$id.$name$extra; ";
> - }
> - } else {
> - my $type;
> - my $names;
> - $arg =~ s/^\s+//;
> - $arg =~ s/\s+$//;
> - # Handle bitmaps
> - $arg =~ s/:\s*\d+\s*//g;
> - # Handle arrays
> - $arg =~ s/\[.*\]//g;
> - # The type may have multiple words,
> - # and multiple IDs can be defined, like:
> - # const struct foo, *bar, foobar
> - # So, we remove spaces when parsing the
> - # names, in order to match just names
> - # and commas for the names
> - $arg =~ s/\s*,\s*/,/g;
> - if ($arg =~ m/(.*)\s+([\S+,]+)/) {
> - $type = $1;
> - $names = $2;
> - } else {
> - $newmember .= "$arg; ";
> - next;
> - }
> - foreach my $name (split /,/, $names) {
> - $name =~ s/^\s*\**(\S+)\s*/$1/;
> - next if (($name =~ m/^\s*$/));
> - if ($id =~ m/^\s*$/) {
> - # anonymous struct/union
> - $newmember .= "$type $name; ";
> - } else {
> - $newmember .= "$type $id.$name; ";
> - }
> - }
> - }
> - }
> - }
> - $members =~ s/$struct_members/$newmember/;
> - }
> -
> - # Ignore other nested elements, like enums
> - $members =~ s/(\{[^\{\}]*\})//g;
> -
> - create_parameterlist($members, ';', $file, $declaration_name);
> - check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual);
> -
> - # Adjust declaration for better display
> - $declaration =~ s/([\{;])/$1\n/g;
> - $declaration =~ s/\}\s+;/};/g;
> - # Better handle inlined enums
> - do {} while ($declaration =~ s/(enum\s+\{[^\}]+),([^\n])/$1,\n$2/);
> -
> - my @def_args = split /\n/, $declaration;
> - my $level = 1;
> - $declaration = "";
> - foreach my $clause (@def_args) {
> - $clause =~ s/^\s+//;
> - $clause =~ s/\s+$//;
> - $clause =~ s/\s+/ /;
> - next if (!$clause);
> - $level-- if ($clause =~ m/(\})/ && $level > 1);
> - if (!($clause =~ m/^\s*#/)) {
> - $declaration .= "\t" x $level;
> - }
> - $declaration .= "\t" . $clause . "\n";
> - $level++ if ($clause =~ m/(\{)/ && !($clause =~m/\}/));
> - }
> - output_declaration($declaration_name,
> - 'struct',
> - {'struct' => $declaration_name,
> - 'module' => $modulename,
> - 'definition' => $declaration,
> - 'parameterlist' => \@parameterlist,
> - 'parameterdescs' => \%parameterdescs,
> - 'parametertypes' => \%parametertypes,
> - 'sectionlist' => \@sectionlist,
> - 'sections' => \%sections,
> - 'purpose' => $declaration_purpose,
> - 'type' => $decl_type
> - });
> - } else {
> - print STDERR "${file}:$.: error: Cannot parse struct or union!\n";
> - ++$errors;
> - }
> -}
> -
> -
> -sub show_warnings($$) {
> - my $functype = shift;
> - my $name = shift;
> -
> - return 0 if (defined($nosymbol_table{$name}));
> -
> - return 1 if ($output_selection == OUTPUT_ALL);
> -
> - if ($output_selection == OUTPUT_EXPORTED) {
> - if (defined($function_table{$name})) {
> - return 1;
> - } else {
> - return 0;
> - }
> - }
> - if ($output_selection == OUTPUT_INTERNAL) {
> - if (!($functype eq "function" && defined($function_table{$name}))) {
> - return 1;
> - } else {
> - return 0;
> - }
> - }
> - if ($output_selection == OUTPUT_INCLUDE) {
> - if (defined($function_table{$name})) {
> - return 1;
> - } else {
> - return 0;
> - }
> - }
> - die("Please add the new output type at show_warnings()");
> -}
> -
> -sub dump_enum($$) {
> - my $x = shift;
> - my $file = shift;
> - my $members;
> -
> - # ignore members marked private:
> - $x =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
> - $x =~ s/\/\*\s*private:.*}/}/gosi;
> -
> - $x =~ s@/\*.*?\*/@@gos; # strip comments.
> - # strip #define macros inside enums
> - $x =~ s@#\s*((define|ifdef|if)\s+|endif)[^;]*;@@gos;
> -
> - if ($x =~ /typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;/) {
> - $declaration_name = $2;
> - $members = $1;
> - } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) {
> - $declaration_name = $1;
> - $members = $2;
> - }
> -
> - if ($members) {
> - if ($identifier ne $declaration_name) {
> - if ($identifier eq "") {
> - emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n");
> - } else {
> - emit_warning("${file}:$.", "expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n");
> - }
> - return;
> - }
> - $declaration_name = "(anonymous)" if ($declaration_name eq "");
> -
> - my %_members;
> -
> - $members =~ s/\s+$//;
> - $members =~ s/\([^;]*?[\)]//g;
> -
> - foreach my $arg (split ',', $members) {
> - $arg =~ s/^\s*(\w+).*/$1/;
> - push @parameterlist, $arg;
> - if (!$parameterdescs{$arg}) {
> - $parameterdescs{$arg} = $undescribed;
> - if (show_warnings("enum", $declaration_name)) {
> - emit_warning("${file}:$.", "Enum value '$arg' not described in enum '$declaration_name'\n");
> - }
> - }
> - $_members{$arg} = 1;
> - }
> -
> - while (my ($k, $v) = each %parameterdescs) {
> - if (!exists($_members{$k})) {
> - if (show_warnings("enum", $declaration_name)) {
> - emit_warning("${file}:$.", "Excess enum value '$k' description in '$declaration_name'\n");
> - }
> - }
> - }
> -
> - output_declaration($declaration_name,
> - 'enum',
> - {'enum' => $declaration_name,
> - 'module' => $modulename,
> - 'parameterlist' => \@parameterlist,
> - 'parameterdescs' => \%parameterdescs,
> - 'sectionlist' => \@sectionlist,
> - 'sections' => \%sections,
> - 'purpose' => $declaration_purpose
> - });
> - } else {
> - print STDERR "${file}:$.: error: Cannot parse enum!\n";
> - ++$errors;
> - }
> -}
> -
> -my $typedef_type = qr { ((?:\s+[\w\*]+\b){0,7}\s+(?:\w+\b|\*+))\s* }x;
> -my $typedef_ident = qr { \*?\s*(\w\S+)\s* }x;
> -my $typedef_args = qr { \s*\((.*)\); }x;
> -
> -my $typedef1 = qr { typedef$typedef_type\($typedef_ident\)$typedef_args }x;
> -my $typedef2 = qr { typedef$typedef_type$typedef_ident$typedef_args }x;
> -
> -sub dump_typedef($$) {
> - my $x = shift;
> - my $file = shift;
> -
> - $x =~ s@/\*.*?\*/@@gos; # strip comments.
> -
> - # Parse function typedef prototypes
> - if ($x =~ $typedef1 || $x =~ $typedef2) {
> - $return_type = $1;
> - $declaration_name = $2;
> - my $args = $3;
> - $return_type =~ s/^\s+//;
> -
> - if ($identifier ne $declaration_name) {
> - emit_warning("${file}:$.", "expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n");
> - return;
> - }
> -
> - create_parameterlist($args, ',', $file, $declaration_name);
> -
> - output_declaration($declaration_name,
> - 'function',
> - {'function' => $declaration_name,
> - 'typedef' => 1,
> - 'module' => $modulename,
> - 'functiontype' => $return_type,
> - 'parameterlist' => \@parameterlist,
> - 'parameterdescs' => \%parameterdescs,
> - 'parametertypes' => \%parametertypes,
> - 'sectionlist' => \@sectionlist,
> - 'sections' => \%sections,
> - 'purpose' => $declaration_purpose
> - });
> - return;
> - }
> -
> - while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
> - $x =~ s/\(*.\)\s*;$/;/;
> - $x =~ s/\[*.\]\s*;$/;/;
> - }
> -
> - if ($x =~ /typedef.*\s+(\w+)\s*;/) {
> - $declaration_name = $1;
> -
> - if ($identifier ne $declaration_name) {
> - emit_warning("${file}:$.", "expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n");
> - return;
> - }
> -
> - output_declaration($declaration_name,
> - 'typedef',
> - {'typedef' => $declaration_name,
> - 'module' => $modulename,
> - 'sectionlist' => \@sectionlist,
> - 'sections' => \%sections,
> - 'purpose' => $declaration_purpose
> - });
> - } else {
> - print STDERR "${file}:$.: error: Cannot parse typedef!\n";
> - ++$errors;
> - }
> -}
> -
> -sub save_struct_actual($) {
> - my $actual = shift;
> -
> - # strip all spaces from the actual param so that it looks like one string item
> - $actual =~ s/\s*//g;
> - $struct_actual = $struct_actual . $actual . " ";
> -}
> -
> -sub create_parameterlist($$$$) {
> - my $args = shift;
> - my $splitter = shift;
> - my $file = shift;
> - my $declaration_name = shift;
> - my $type;
> - my $param;
> -
> - # temporarily replace commas inside function pointer definition
> - my $arg_expr = qr{\([^\),]+};
> - while ($args =~ /$arg_expr,/) {
> - $args =~ s/($arg_expr),/$1#/g;
> - }
> -
> - foreach my $arg (split($splitter, $args)) {
> - # strip comments
> - $arg =~ s/\/\*.*\*\///;
> - # ignore argument attributes
> - $arg =~ s/\sPOS0?\s/ /;
> - # strip leading/trailing spaces
> - $arg =~ s/^\s*//;
> - $arg =~ s/\s*$//;
> - $arg =~ s/\s+/ /;
> -
> - if ($arg =~ /^#/) {
> - # Treat preprocessor directive as a typeless variable just to fill
> - # corresponding data structures "correctly". Catch it later in
> - # output_* subs.
> - push_parameter($arg, "", "", $file);
> - } elsif ($arg =~ m/\(.+\)\s*\(/) {
> - # pointer-to-function
> - $arg =~ tr/#/,/;
> - $arg =~ m/[^\(]+\(\*?\s*([\w\[\]\.]*)\s*\)/;
> - $param = $1;
> - $type = $arg;
> - $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
> - save_struct_actual($param);
> - push_parameter($param, $type, $arg, $file, $declaration_name);
> - } elsif ($arg =~ m/\(.+\)\s*\[/) {
> - # array-of-pointers
> - $arg =~ tr/#/,/;
> - $arg =~ m/[^\(]+\(\s*\*\s*([\w\[\]\.]*?)\s*(\s*\[\s*[\w]+\s*\]\s*)*\)/;
> - $param = $1;
> - $type = $arg;
> - $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
> - save_struct_actual($param);
> - push_parameter($param, $type, $arg, $file, $declaration_name);
> - } elsif ($arg) {
> - $arg =~ s/\s*:\s*/:/g;
> - $arg =~ s/\s*\[/\[/g;
> -
> - my @args = split('\s*,\s*', $arg);
> - if ($args[0] =~ m/\*/) {
> - $args[0] =~ s/(\*+)\s*/ $1/;
> - }
> -
> - my @first_arg;
> - if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
> - shift @args;
> - push(@first_arg, split('\s+', $1));
> - push(@first_arg, $2);
> - } else {
> - @first_arg = split('\s+', shift @args);
> - }
> -
> - unshift(@args, pop @first_arg);
> - $type = join " ", @first_arg;
> -
> - foreach $param (@args) {
> - if ($param =~ m/^(\*+)\s*(.*)/) {
> - save_struct_actual($2);
> -
> - push_parameter($2, "$type $1", $arg, $file, $declaration_name);
> - } elsif ($param =~ m/(.*?):(\w+)/) {
> - if ($type ne "") { # skip unnamed bit-fields
> - save_struct_actual($1);
> - push_parameter($1, "$type:$2", $arg, $file, $declaration_name)
> - }
> - } else {
> - save_struct_actual($param);
> - push_parameter($param, $type, $arg, $file, $declaration_name);
> - }
> - }
> - }
> - }
> -}
> -
> -sub push_parameter($$$$$) {
> - my $param = shift;
> - my $type = shift;
> - my $org_arg = shift;
> - my $file = shift;
> - my $declaration_name = shift;
> -
> - if (($anon_struct_union == 1) && ($type eq "") &&
> - ($param eq "}")) {
> - return; # ignore the ending }; from anon. struct/union
> - }
> -
> - $anon_struct_union = 0;
> - $param =~ s/[\[\)].*//;
> -
> - if ($type eq "" && $param =~ /\.\.\.$/)
> - {
> - if (!$param =~ /\w\.\.\.$/) {
> - # handles unnamed variable parameters
> - $param = "...";
> - } elsif ($param =~ /\w\.\.\.$/) {
> - # for named variable parameters of the form `x...`, remove the dots
> - $param =~ s/\.\.\.$//;
> - }
> - if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
> - $parameterdescs{$param} = "variable arguments";
> - }
> - }
> - elsif ($type eq "" && ($param eq "" or $param eq "void"))
> - {
> - $param="void";
> - $parameterdescs{void} = "no arguments";
> - }
> - elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
> - # handle unnamed (anonymous) union or struct:
> - {
> - $type = $param;
> - $param = "{unnamed_" . $param . "}";
> - $parameterdescs{$param} = "anonymous\n";
> - $anon_struct_union = 1;
> - }
> - elsif ($param =~ "__cacheline_group" )
> - # handle cache group enforcing variables: they do not need be described in header files
> - {
> - return; # ignore __cacheline_group_begin and __cacheline_group_end
> - }
> -
> - # warn if parameter has no description
> - # (but ignore ones starting with # as these are not parameters
> - # but inline preprocessor statements);
> - # Note: It will also ignore void params and unnamed structs/unions
> - if (!defined $parameterdescs{$param} && $param !~ /^#/) {
> - $parameterdescs{$param} = $undescribed;
> -
> - if (show_warnings($type, $declaration_name) && $param !~ /\./) {
> - emit_warning("${file}:$.", "Function parameter or struct member '$param' not described in '$declaration_name'\n");
> - }
> - }
> -
> - # strip spaces from $param so that it is one continuous string
> - # on @parameterlist;
> - # this fixes a problem where check_sections() cannot find
> - # a parameter like "addr[6 + 2]" because it actually appears
> - # as "addr[6", "+", "2]" on the parameter list;
> - # but it's better to maintain the param string unchanged for output,
> - # so just weaken the string compare in check_sections() to ignore
> - # "[blah" in a parameter string;
> - ###$param =~ s/\s*//g;
> - push @parameterlist, $param;
> - $org_arg =~ s/\s\s+/ /g;
> - $parametertypes{$param} = $org_arg;
> -}
> -
> -sub check_sections($$$$$) {
> - my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck) = @_;
> - my @sects = split ' ', $sectcheck;
> - my @prms = split ' ', $prmscheck;
> - my $err;
> - my ($px, $sx);
> - my $prm_clean; # strip trailing "[array size]" and/or beginning "*"
> -
> - foreach $sx (0 .. $#sects) {
> - $err = 1;
> - foreach $px (0 .. $#prms) {
> - $prm_clean = $prms[$px];
> - $prm_clean =~ s/\[.*\]//;
> - $prm_clean =~ s/$attribute//i;
> - # ignore array size in a parameter string;
> - # however, the original param string may contain
> - # spaces, e.g.: addr[6 + 2]
> - # and this appears in @prms as "addr[6" since the
> - # parameter list is split at spaces;
> - # hence just ignore "[..." for the sections check;
> - $prm_clean =~ s/\[.*//;
> -
> - ##$prm_clean =~ s/^\**//;
> - if ($prm_clean eq $sects[$sx]) {
> - $err = 0;
> - last;
> - }
> - }
> - if ($err) {
> - if ($decl_type eq "function") {
> - emit_warning("${file}:$.",
> - "Excess function parameter " .
> - "'$sects[$sx]' " .
> - "description in '$decl_name'\n");
> - } elsif (($decl_type eq "struct") or
> - ($decl_type eq "union")) {
> - emit_warning("${file}:$.",
> - "Excess $decl_type member " .
> - "'$sects[$sx]' " .
> - "description in '$decl_name'\n");
> - }
> - }
> - }
> -}
> -
> -##
> -# Checks the section describing the return value of a function.
> -sub check_return_section {
> - my $file = shift;
> - my $declaration_name = shift;
> - my $return_type = shift;
> -
> - # Ignore an empty return type (It's a macro)
> - # Ignore functions with a "void" return type. (But don't ignore "void *")
> - if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
> - return;
> - }
> -
> - if (!defined($sections{$section_return}) ||
> - $sections{$section_return} eq "")
> - {
> - emit_warning("${file}:$.",
> - "No description found for return value of " .
> - "'$declaration_name'\n");
> - }
> -}
> -
> -##
> -# takes a function prototype and the name of the current file being
> -# processed and spits out all the details stored in the global
> -# arrays/hashes.
> -sub dump_function($$) {
> - my $prototype = shift;
> - my $file = shift;
> - my $func_macro = 0;
> -
> - print_lineno($new_start_line);
> -
> - $prototype =~ s/^static +//;
> - $prototype =~ s/^extern +//;
> - $prototype =~ s/^asmlinkage +//;
> - $prototype =~ s/^inline +//;
> - $prototype =~ s/^__inline__ +//;
> - $prototype =~ s/^__inline +//;
> - $prototype =~ s/^__always_inline +//;
> - $prototype =~ s/^noinline +//;
> - $prototype =~ s/^__FORTIFY_INLINE +//;
> - $prototype =~ s/__init +//;
> - $prototype =~ s/__init_or_module +//;
> - $prototype =~ s/__deprecated +//;
> - $prototype =~ s/__flatten +//;
> - $prototype =~ s/__meminit +//;
> - $prototype =~ s/__must_check +//;
> - $prototype =~ s/__weak +//;
> - $prototype =~ s/__sched +//;
> - $prototype =~ s/_noprof//;
> - $prototype =~ s/__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +//;
> - $prototype =~ s/__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +//;
> - $prototype =~ s/__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +//;
> - $prototype =~ s/DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)/$1, $2/;
> - my $define = $prototype =~ s/^#\s*define\s+//; #ak added
> - $prototype =~ s/__attribute_const__ +//;
> - $prototype =~ s/__attribute__\s*\(\(
> - (?:
> - [\w\s]++ # attribute name
> - (?:\([^)]*+\))? # attribute arguments
> - \s*+,? # optional comma at the end
> - )+
> - \)\)\s+//x;
> -
> - # Yes, this truly is vile. We are looking for:
> - # 1. Return type (may be nothing if we're looking at a macro)
> - # 2. Function name
> - # 3. Function parameters.
> - #
> - # All the while we have to watch out for function pointer parameters
> - # (which IIRC is what the two sections are for), C types (these
> - # regexps don't even start to express all the possibilities), and
> - # so on.
> - #
> - # If you mess with these regexps, it's a good idea to check that
> - # the following functions' documentation still comes out right:
> - # - parport_register_device (function pointer parameters)
> - # - atomic_set (macro)
> - # - pci_match_device, __copy_to_user (long return type)
> - my $name = qr{[a-zA-Z0-9_~:]+};
> - my $prototype_end1 = qr{[^\(]*};
> - my $prototype_end2 = qr{[^\{]*};
> - my $prototype_end = qr{\(($prototype_end1|$prototype_end2)\)};
> - my $type1 = qr{[\w\s]+};
> - my $type2 = qr{$type1\*+};
> -
> - if ($define && $prototype =~ m/^()($name)\s+/) {
> - # This is an object-like macro, it has no return type and no parameter
> - # list.
> - # Function-like macros are not allowed to have spaces between
> - # declaration_name and opening parenthesis (notice the \s+).
> - $return_type = $1;
> - $declaration_name = $2;
> - $func_macro = 1;
> - } elsif ($prototype =~ m/^()($name)\s*$prototype_end/ ||
> - $prototype =~ m/^($type1)\s+($name)\s*$prototype_end/ ||
> - $prototype =~ m/^($type2+)\s*($name)\s*$prototype_end/) {
> - $return_type = $1;
> - $declaration_name = $2;
> - my $args = $3;
> -
> - create_parameterlist($args, ',', $file, $declaration_name);
> - } else {
> - emit_warning("${file}:$.", "cannot understand function prototype: '$prototype'\n");
> - return;
> - }
> -
> - if ($identifier ne $declaration_name) {
> - emit_warning("${file}:$.", "expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n");
> - return;
> - }
> -
> - my $prms = join " ", @parameterlist;
> - check_sections($file, $declaration_name, "function", $sectcheck, $prms);
> -
> - # This check emits a lot of warnings at the moment, because many
> - # functions don't have a 'Return' doc section. So until the number
> - # of warnings goes sufficiently down, the check is only performed in
> - # -Wreturn mode.
> - # TODO: always perform the check.
> - if ($Wreturn && !$func_macro) {
> - check_return_section($file, $declaration_name, $return_type);
> - }
> -
> - # The function parser can be called with a typedef parameter.
> - # Handle it.
> - if ($return_type =~ /typedef/) {
> - output_declaration($declaration_name,
> - 'function',
> - {'function' => $declaration_name,
> - 'typedef' => 1,
> - 'module' => $modulename,
> - 'functiontype' => $return_type,
> - 'parameterlist' => \@parameterlist,
> - 'parameterdescs' => \%parameterdescs,
> - 'parametertypes' => \%parametertypes,
> - 'sectionlist' => \@sectionlist,
> - 'sections' => \%sections,
> - 'purpose' => $declaration_purpose,
> - 'func_macro' => $func_macro
> - });
> - } else {
> - output_declaration($declaration_name,
> - 'function',
> - {'function' => $declaration_name,
> - 'module' => $modulename,
> - 'functiontype' => $return_type,
> - 'parameterlist' => \@parameterlist,
> - 'parameterdescs' => \%parameterdescs,
> - 'parametertypes' => \%parametertypes,
> - 'sectionlist' => \@sectionlist,
> - 'sections' => \%sections,
> - 'purpose' => $declaration_purpose,
> - 'func_macro' => $func_macro
> - });
> - }
> -}
> -
> -sub reset_state {
> - $function = "";
> - %parameterdescs = ();
> - %parametertypes = ();
> - @parameterlist = ();
> - %sections = ();
> - @sectionlist = ();
> - $sectcheck = "";
> - $struct_actual = "";
> - $prototype = "";
> -
> - $state = STATE_NORMAL;
> - $inline_doc_state = STATE_INLINE_NA;
> -}
> -
> -sub tracepoint_munge($) {
> - my $file = shift;
> - my $tracepointname = 0;
> - my $tracepointargs = 0;
> -
> - if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
> - $tracepointname = $1;
> - }
> - if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
> - $tracepointname = $1;
> - }
> - if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
> - $tracepointname = $2;
> - }
> - $tracepointname =~ s/^\s+//; #strip leading whitespace
> - if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
> - $tracepointargs = $1;
> - }
> - if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
> - emit_warning("${file}:$.", "Unrecognized tracepoint format: \n".
> - "$prototype\n");
> - } else {
> - $prototype = "static inline void trace_$tracepointname($tracepointargs)";
> - $identifier = "trace_$identifier";
> - }
> -}
> -
> -sub syscall_munge() {
> - my $void = 0;
> -
> - $prototype =~ s@[\r\n]+@ @gos; # strip newlines/CR's
> -## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
> - if ($prototype =~ m/SYSCALL_DEFINE0/) {
> - $void = 1;
> -## $prototype = "long sys_$1(void)";
> - }
> -
> - $prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
> - if ($prototype =~ m/long (sys_.*?),/) {
> - $prototype =~ s/,/\(/;
> - } elsif ($void) {
> - $prototype =~ s/\)/\(void\)/;
> - }
> -
> - # now delete all of the odd-number commas in $prototype
> - # so that arg types & arg names don't have a comma between them
> - my $count = 0;
> - my $len = length($prototype);
> - if ($void) {
> - $len = 0; # skip the for-loop
> - }
> - for (my $ix = 0; $ix < $len; $ix++) {
> - if (substr($prototype, $ix, 1) eq ',') {
> - $count++;
> - if ($count % 2 == 1) {
> - substr($prototype, $ix, 1) = ' ';
> - }
> - }
> - }
> -}
> -
> -sub process_proto_function($$) {
> - my $x = shift;
> - my $file = shift;
> -
> - $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
> -
> - if ($x =~ /^#/ && $x !~ /^#\s*define/) {
> - # do nothing
> - } elsif ($x =~ /([^\{]*)/) {
> - $prototype .= $1;
> - }
> -
> - if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
> - $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
> - $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
> - $prototype =~ s@^\s+@@gos; # strip leading spaces
> -
> - # Handle prototypes for function pointers like:
> - # int (*pcs_config)(struct foo)
> - $prototype =~ s@^(\S+\s+)\(\s*\*(\S+)\)@$1$2@gos;
> -
> - if ($prototype =~ /SYSCALL_DEFINE/) {
> - syscall_munge();
> - }
> - if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
> - $prototype =~ /DEFINE_SINGLE_EVENT/)
> - {
> - tracepoint_munge($file);
> - }
> - dump_function($prototype, $file);
> - reset_state();
> - }
> -}
> -
> -sub process_proto_type($$) {
> - my $x = shift;
> - my $file = shift;
> -
> - $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
> - $x =~ s@^\s+@@gos; # strip leading spaces
> - $x =~ s@\s+$@@gos; # strip trailing spaces
> - $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
> -
> - if ($x =~ /^#/) {
> - # To distinguish preprocessor directive from regular declaration later.
> - $x .= ";";
> - }
> -
> - while (1) {
> - if ( $x =~ /([^\{\};]*)([\{\};])(.*)/ ) {
> - if( length $prototype ) {
> - $prototype .= " "
> - }
> - $prototype .= $1 . $2;
> - ($2 eq '{') && $brcount++;
> - ($2 eq '}') && $brcount--;
> - if (($2 eq ';') && ($brcount == 0)) {
> - dump_declaration($prototype, $file);
> - reset_state();
> - last;
> - }
> - $x = $3;
> - } else {
> - $prototype .= $x;
> - last;
> - }
> - }
> -}
> -
> -
> -sub map_filename($) {
> - my $file;
> - my ($orig_file) = @_;
> -
> - if (defined($ENV{'SRCTREE'})) {
> - $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
> - } else {
> - $file = $orig_file;
> - }
> -
> - return $file;
> -}
> -
> -sub process_export_file($) {
> - my ($orig_file) = @_;
> - my $file = map_filename($orig_file);
> -
> - if (!open(IN,"<$file")) {
> - print STDERR "Error: Cannot open file $file\n";
> - ++$errors;
> - return;
> - }
> -
> - while (<IN>) {
> - if (/$export_symbol/) {
> - next if (defined($nosymbol_table{$2}));
> - $function_table{$2} = 1;
> - }
> - if (/$export_symbol_ns/) {
> - next if (defined($nosymbol_table{$2}));
> - $function_table{$2} = 1;
> - }
> - }
> -
> - close(IN);
> -}
> -
> -#
> -# Parsers for the various processing states.
> -#
> -# STATE_NORMAL: looking for the /** to begin everything.
> -#
> -sub process_normal() {
> - if (/$doc_start/o) {
> - $state = STATE_NAME; # next line is always the function name
> - $declaration_start_line = $. + 1;
> - }
> -}
> -
> -#
> -# STATE_NAME: Looking for the "name - description" line
> -#
> -sub process_name($$) {
> - my $file = shift;
> - my $descr;
> -
> - if (/$doc_block/o) {
> - $state = STATE_DOCBLOCK;
> - $contents = "";
> - $new_start_line = $.;
> -
> - if ( $1 eq "" ) {
> - $section = $section_intro;
> - } else {
> - $section = $1;
> - }
> - } elsif (/$doc_decl/o) {
> - $identifier = $1;
> - my $is_kernel_comment = 0;
> - my $decl_start = qr{$doc_com};
> - # test for pointer declaration type, foo * bar() - desc
> - my $fn_type = qr{\w+\s*\*\s*};
> - my $parenthesis = qr{\(\w*\)};
> - my $decl_end = qr{[-:].*};
> - if (/^$decl_start([\w\s]+?)$parenthesis?\s*$decl_end?$/) {
> - $identifier = $1;
> - }
> - if ($identifier =~ m/^(struct|union|enum|typedef)\b\s*(\S*)/) {
> - $decl_type = $1;
> - $identifier = $2;
> - $is_kernel_comment = 1;
> - }
> - # Look for foo() or static void foo() - description; or misspelt
> - # identifier
> - elsif (/^$decl_start$fn_type?(\w+)\s*$parenthesis?\s*$decl_end?$/ ||
> - /^$decl_start$fn_type?(\w+[^-:]*)$parenthesis?\s*$decl_end$/) {
> - $identifier = $1;
> - $decl_type = 'function';
> - $identifier =~ s/^define\s+//;
> - $is_kernel_comment = 1;
> - }
> - $identifier =~ s/\s+$//;
> -
> - $state = STATE_BODY;
> - # if there's no @param blocks need to set up default section
> - # here
> - $contents = "";
> - $section = $section_default;
> - $new_start_line = $. + 1;
> - if (/[-:](.*)/) {
> - # strip leading/trailing/multiple spaces
> - $descr= $1;
> - $descr =~ s/^\s*//;
> - $descr =~ s/\s*$//;
> - $descr =~ s/\s+/ /g;
> - $declaration_purpose = $descr;
> - $state = STATE_BODY_MAYBE;
> - } else {
> - $declaration_purpose = "";
> - }
> -
> - if (!$is_kernel_comment) {
> - emit_warning("${file}:$.", "This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n$_");
> - $state = STATE_NORMAL;
> - }
> -
> - if (($declaration_purpose eq "") && $Wshort_desc) {
> - emit_warning("${file}:$.", "missing initial short description on line:\n$_");
> - }
> -
> - if ($identifier eq "" && $decl_type ne "enum") {
> - emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n$_");
> - $state = STATE_NORMAL;
> - }
> -
> - if ($verbose) {
> - print STDERR "${file}:$.: info: Scanning doc for $decl_type $identifier\n";
> - }
> - } else {
> - emit_warning("${file}:$.", "Cannot understand $_ on line $. - I thought it was a doc line\n");
> - $state = STATE_NORMAL;
> - }
> -}
> -
> -
> -#
> -# STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment.
> -#
> -sub process_body($$) {
> - my $file = shift;
> -
> - if ($state == STATE_BODY_WITH_BLANK_LINE && /^\s*\*\s?\S/) {
> - dump_section($file, $section, $contents);
> - $section = $section_default;
> - $new_start_line = $.;
> - $contents = "";
> - }
> -
> - if (/$doc_sect/i) { # case insensitive for supported section names
> - $newsection = $1;
> - $newcontents = $2;
> -
> - # map the supported section names to the canonical names
> - if ($newsection =~ m/^description$/i) {
> - $newsection = $section_default;
> - } elsif ($newsection =~ m/^context$/i) {
> - $newsection = $section_context;
> - } elsif ($newsection =~ m/^returns?$/i) {
> - $newsection = $section_return;
> - } elsif ($newsection =~ m/^\@return$/) {
> - # special: @return is a section, not a param description
> - $newsection = $section_return;
> - }
> -
> - if (($contents ne "") && ($contents ne "\n")) {
> - dump_section($file, $section, $contents);
> - $section = $section_default;
> - }
> -
> - $state = STATE_BODY;
> - $contents = $newcontents;
> - $new_start_line = $.;
> - while (substr($contents, 0, 1) eq " ") {
> - $contents = substr($contents, 1);
> - }
> - if ($contents ne "") {
> - $contents .= "\n";
> - }
> - $section = $newsection;
> - $leading_space = undef;
> - } elsif (/$doc_end/) {
> - if (($contents ne "") && ($contents ne "\n")) {
> - dump_section($file, $section, $contents);
> - $section = $section_default;
> - $contents = "";
> - }
> - # look for doc_com + <text> + doc_end:
> - if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
> - emit_warning("${file}:$.", "suspicious ending line: $_");
> - }
> -
> - $prototype = "";
> - $state = STATE_PROTO;
> - $brcount = 0;
> - $new_start_line = $. + 1;
> - } elsif (/$doc_content/) {
> - if ($1 eq "") {
> - if ($section eq $section_context) {
> - dump_section($file, $section, $contents);
> - $section = $section_default;
> - $contents = "";
> - $new_start_line = $.;
> - $state = STATE_BODY;
> - } else {
> - if ($section ne $section_default) {
> - $state = STATE_BODY_WITH_BLANK_LINE;
> - } else {
> - $state = STATE_BODY;
> - }
> - $contents .= "\n";
> - }
> - } elsif ($state == STATE_BODY_MAYBE) {
> - # Continued declaration purpose
> - chomp($declaration_purpose);
> - $declaration_purpose .= " " . $1;
> - $declaration_purpose =~ s/\s+/ /g;
> - } else {
> - my $cont = $1;
> - if ($section =~ m/^@/ || $section eq $section_context) {
> - if (!defined $leading_space) {
> - if ($cont =~ m/^(\s+)/) {
> - $leading_space = $1;
> - } else {
> - $leading_space = "";
> - }
> - }
> - $cont =~ s/^$leading_space//;
> - }
> - $contents .= $cont . "\n";
> - }
> - } else {
> - # i dont know - bad line? ignore.
> - emit_warning("${file}:$.", "bad line: $_");
> - }
> -}
> -
> -
> -#
> -# STATE_PROTO: reading a function/whatever prototype.
> -#
> -sub process_proto($$) {
> - my $file = shift;
> -
> - if (/$doc_inline_oneline/) {
> - $section = $1;
> - $contents = $2;
> - if ($contents ne "") {
> - $contents .= "\n";
> - dump_section($file, $section, $contents);
> - $section = $section_default;
> - $contents = "";
> - }
> - } elsif (/$doc_inline_start/) {
> - $state = STATE_INLINE;
> - $inline_doc_state = STATE_INLINE_NAME;
> - } elsif ($decl_type eq 'function') {
> - process_proto_function($_, $file);
> - } else {
> - process_proto_type($_, $file);
> - }
> -}
> -
> -#
> -# STATE_DOCBLOCK: within a DOC: block.
> -#
> -sub process_docblock($$) {
> - my $file = shift;
> -
> - if (/$doc_end/) {
> - dump_doc_section($file, $section, $contents);
> - $section = $section_default;
> - $contents = "";
> - $function = "";
> - %parameterdescs = ();
> - %parametertypes = ();
> - @parameterlist = ();
> - %sections = ();
> - @sectionlist = ();
> - $prototype = "";
> - $state = STATE_NORMAL;
> - } elsif (/$doc_content/) {
> - if ( $1 eq "" ) {
> - $contents .= $blankline;
> - } else {
> - $contents .= $1 . "\n";
> - }
> - }
> -}
> -
> -#
> -# STATE_INLINE: docbook comments within a prototype.
> -#
> -sub process_inline($$) {
> - my $file = shift;
> -
> - # First line (state 1) needs to be a @parameter
> - if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
> - $section = $1;
> - $contents = $2;
> - $new_start_line = $.;
> - if ($contents ne "") {
> - while (substr($contents, 0, 1) eq " ") {
> - $contents = substr($contents, 1);
> - }
> - $contents .= "\n";
> - }
> - $inline_doc_state = STATE_INLINE_TEXT;
> - # Documentation block end */
> - } elsif (/$doc_inline_end/) {
> - if (($contents ne "") && ($contents ne "\n")) {
> - dump_section($file, $section, $contents);
> - $section = $section_default;
> - $contents = "";
> - }
> - $state = STATE_PROTO;
> - $inline_doc_state = STATE_INLINE_NA;
> - # Regular text
> - } elsif (/$doc_content/) {
> - if ($inline_doc_state == STATE_INLINE_TEXT) {
> - $contents .= $1 . "\n";
> - # nuke leading blank lines
> - if ($contents =~ /^\s*$/) {
> - $contents = "";
> - }
> - } elsif ($inline_doc_state == STATE_INLINE_NAME) {
> - $inline_doc_state = STATE_INLINE_ERROR;
> - emit_warning("${file}:$.", "Incorrect use of kernel-doc format: $_");
> - }
> - }
> -}
> -
> -
> -sub process_file($) {
> - my $file;
> - my ($orig_file) = @_;
> -
> - $file = map_filename($orig_file);
> -
> - if (!open(IN_FILE,"<$file")) {
> - print STDERR "Error: Cannot open file $file\n";
> - ++$errors;
> - return;
> - }
> -
> - $. = 1;
> -
> - $section_counter = 0;
> - while (<IN_FILE>) {
> - while (!/^ \*/ && s/\\\s*$//) {
> - $_ .= <IN_FILE>;
> - }
> - # Replace tabs by spaces
> - while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
> - # Hand this line to the appropriate state handler
> - if ($state == STATE_NORMAL) {
> - process_normal();
> - } elsif ($state == STATE_NAME) {
> - process_name($file, $_);
> - } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE ||
> - $state == STATE_BODY_WITH_BLANK_LINE) {
> - process_body($file, $_);
> - } elsif ($state == STATE_INLINE) { # scanning for inline parameters
> - process_inline($file, $_);
> - } elsif ($state == STATE_PROTO) {
> - process_proto($file, $_);
> - } elsif ($state == STATE_DOCBLOCK) {
> - process_docblock($file, $_);
> - }
> - }
> -
> - # Make sure we got something interesting.
> - if (!$section_counter && $output_mode ne "none") {
> - if ($output_selection == OUTPUT_INCLUDE) {
> - emit_warning("${file}:1", "'$_' not found\n")
> - for keys %function_table;
> - } else {
> - emit_warning("${file}:1", "no structured comments found\n");
> - }
> - }
> - close IN_FILE;
> -}
> -
> -$kernelversion = get_kernel_version();
> -
> -# generate a sequence of code that will splice in highlighting information
> -# using the s// operator.
> -for (my $k = 0; $k < @highlights; $k++) {
> - my $pattern = $highlights[$k][0];
> - my $result = $highlights[$k][1];
> -# print STDERR "scanning pattern:$pattern, highlight:($result)\n";
> - $dohighlight .= "\$contents =~ s:$pattern:$result:gs;\n";
> -}
> -
> -if ($output_selection == OUTPUT_EXPORTED ||
> - $output_selection == OUTPUT_INTERNAL) {
> -
> - push(@export_file_list, @ARGV);
> -
> - foreach (@export_file_list) {
> - chomp;
> - process_export_file($_);
> - }
> -}
> -
> -foreach (@ARGV) {
> - chomp;
> - process_file($_);
> -}
> -if ($verbose && $errors) {
> - print STDERR "$errors errors\n";
> -}
> -if ($verbose && $warnings) {
> - print STDERR "$warnings warnings\n";
> -}
> -
> -if ($Werror && $warnings) {
> - print STDERR "$warnings warnings as Errors\n";
> - exit($warnings);
> -} else {
> - exit($output_mode eq "none" ? 0 : $errors)
> -}
> -
> -__END__
> -
> -=head1 OPTIONS
> -
> -=head2 Output format selection (mutually exclusive):
> -
> -=over 8
> -
> -=item -man
> -
> -Output troff manual page format.
> -
> -=item -rst
> -
> -Output reStructuredText format. This is the default.
> -
> -=item -none
> -
> -Do not output documentation, only warnings.
> -
> -=back
> -
> -=head2 Output format modifiers
> -
> -=head3 reStructuredText only
> -
> -=head2 Output selection (mutually exclusive):
> -
> -=over 8
> -
> -=item -export
> -
> -Only output documentation for the symbols that have been exported using
> -EXPORT_SYMBOL() and related macros in any input FILE or -export-file FILE.
> -
> -=item -internal
> -
> -Only output documentation for the symbols that have NOT been exported using
> -EXPORT_SYMBOL() and related macros in any input FILE or -export-file FILE.
> -
> -=item -function NAME
> -
> -Only output documentation for the given function or DOC: section title.
> -All other functions and DOC: sections are ignored.
> -
> -May be specified multiple times.
> -
> -=item -nosymbol NAME
> -
> -Exclude the specified symbol from the output documentation.
> -
> -May be specified multiple times.
> -
> -=back
> -
> -=head2 Output selection modifiers:
> -
> -=over 8
> -
> -=item -no-doc-sections
> -
> -Do not output DOC: sections.
> -
> -=item -export-file FILE
> -
> -Specify an additional FILE in which to look for EXPORT_SYMBOL information.
> -
> -To be used with -export or -internal.
> -
> -May be specified multiple times.
> -
> -=back
> -
> -=head3 reStructuredText only
> -
> -=over 8
> -
> -=item -enable-lineno
> -
> -Enable output of .. LINENO lines.
> -
> -=back
> -
> -=head2 Other parameters:
> -
> -=over 8
> -
> -=item -h, -help
> -
> -Print this help.
> -
> -=item -v
> -
> -Verbose output, more warnings and other information.
> -
> -=item -Werror
> -
> -Treat warnings as errors.
> -
> -=back
> -
> -=cut
Thanks,
Mauro
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 10/13] docs: move kernel-doc to tools/doc
2025-08-13 21:32 ` [PATCH 10/13] docs: move kernel-doc " Jonathan Corbet
@ 2025-08-13 23:33 ` Mauro Carvalho Chehab
2025-08-13 23:48 ` Mauro Carvalho Chehab
2025-08-14 12:13 ` kernel test robot
2 siblings, 0 replies; 47+ messages in thread
From: Mauro Carvalho Chehab @ 2025-08-13 23:33 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Akira Yokosawa, Randy Dunlap
Em Wed, 13 Aug 2025 15:32:09 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> Move kernel-doc to join the rest of the tools, and update references
> throughout the tree.
>
LGTM.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
> Documentation/conf.py | 2 +-
> Documentation/doc-guide/kernel-doc.rst | 12 ++++++------
> Documentation/kbuild/kbuild.rst | 2 +-
> Documentation/process/coding-style.rst | 2 +-
> .../translations/it_IT/doc-guide/kernel-doc.rst | 8 ++++----
> .../translations/sp_SP/process/coding-style.rst | 2 +-
> .../translations/zh_CN/doc-guide/kernel-doc.rst | 10 +++++-----
> Documentation/translations/zh_CN/kbuild/kbuild.rst | 2 +-
> .../translations/zh_CN/process/coding-style.rst | 2 +-
> .../translations/zh_TW/process/coding-style.rst | 2 +-
> MAINTAINERS | 1 -
> Makefile | 2 +-
> drivers/gpu/drm/i915/Makefile | 2 +-
> scripts/find-unused-docs.sh | 2 +-
> scripts/kernel-doc | 1 -
> scripts/kernel-doc.py => tools/doc/kernel-doc | 0
> 16 files changed, 25 insertions(+), 27 deletions(-)
> delete mode 120000 scripts/kernel-doc
> rename scripts/kernel-doc.py => tools/doc/kernel-doc (100%)
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index f9828f3862f9..600cf5d32af8 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -564,7 +564,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/doc/kernel-doc.py"
> kerneldoc_srctree = ".."
>
> # ------------------------------------------------------------------------------
> diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
> index af9697e60165..6fc89d444ada 100644
> --- a/Documentation/doc-guide/kernel-doc.rst
> +++ b/Documentation/doc-guide/kernel-doc.rst
> @@ -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/doc/kernel-doc -v -none drivers/foo/bar.c
>
> The documentation format is verified by the kernel build when it is
> requested to perform extra gcc checks::
> @@ -349,7 +349,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/doc/kernel-doc``.
> They may have a parameter list. Object-like macros have do not have a
> parameter list.
>
> @@ -571,7 +571,7 @@ 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
> +``tools/doc/kernel-doc`` script to extract the documentation comments from the
> source.
>
> .. _kernel_doc:
> @@ -582,17 +582,17 @@ How to use kernel-doc to generate man pages
> If you just want to use kernel-doc to generate man pages you can do this
> from the kernel git tree::
>
> - $ scripts/kernel-doc -man \
> + $ tools/doc/kernel-doc -man \
> $(git grep -l '/\*\*' -- :^Documentation :^tools) \
> | scripts/split-man.pl /tmp/man
>
> Some older versions of git do not support some of the variants of syntax for
> path exclusion. One of the following commands may work for those versions::
>
> - $ scripts/kernel-doc -man \
> + $ tools/doc/kernel-doc -man \
> $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
> | scripts/split-man.pl /tmp/man
>
> - $ scripts/kernel-doc -man \
> + $ tools/doc/kernel-doc -man \
> $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
> | scripts/split-man.pl /tmp/man
> diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst
> index 3388a10f2dcc..ae7b0669e3ec 100644
> --- a/Documentation/kbuild/kbuild.rst
> +++ b/Documentation/kbuild/kbuild.rst
> @@ -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/doc/kernel-doc for which flags are supported. Note that this doesn't
> (currently) apply to documentation builds.
>
> ARCH
> diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> index d1a8e5465ed9..b2d16449a27b 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -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/doc/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.
> diff --git a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
> index aa0e31d353d6..05ea0f03c80b 100644
> --- a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
> +++ b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
> @@ -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/doc/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/doc/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/doc/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/doc/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man
> diff --git a/Documentation/translations/sp_SP/process/coding-style.rst b/Documentation/translations/sp_SP/process/coding-style.rst
> index 025223be9706..73c43b49480f 100644
> --- a/Documentation/translations/sp_SP/process/coding-style.rst
> +++ b/Documentation/translations/sp_SP/process/coding-style.rst
> @@ -633,7 +633,7 @@ posiblemente POR QUÉ hace esto.
>
> 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/doc/kernel-doc`` para más detalles.
>
> El estilo preferido para comentarios largos (de varias líneas) es:
>
> diff --git a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
> index ccfb9b8329c2..b242e52f911c 100644
> --- a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
> +++ b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
> @@ -43,7 +43,7 @@ kernel-doc注释用 ``/**`` 作为开始标记。 ``kernel-doc`` 工具将提取
> 用详细模式和不生成实际输出来运行 ``kernel-doc`` 工具，可以验证文档注释的格式
> 是否正确。例如::
>
> - scripts/kernel-doc -v -none drivers/foo/bar.c
> + tools/doc/kernel-doc -v -none drivers/foo/bar.c
>
> 当请求执行额外的gcc检查时，内核构建将验证文档格式::
>
> @@ -473,7 +473,7 @@ doc: *title*
> 如果没有选项，kernel-doc指令将包含源文件中的所有文档注释。
>
> kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/kerneldoc.py`` 。
> -在内部，它使用 ``scripts/kernel-doc`` 脚本从源代码中提取文档注释。
> +在内部，它使用 ``tools/doc/kernel-doc`` 脚本从源代码中提取文档注释。
>
> .. _kernel_doc_zh:
>
> @@ -482,18 +482,18 @@ kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/k
>
> 如果您只想使用kernel-doc生成手册页，可以从内核git树这样做::
>
> - $ scripts/kernel-doc -man \
> + $ tools/doc/kernel-doc -man \
> $(git grep -l '/\*\*' -- :^Documentation :^tools) \
> | scripts/split-man.pl /tmp/man
>
> 一些旧版本的git不支持路径排除语法的某些变体。
> 以下命令之一可能适用于这些版本::
>
> - $ scripts/kernel-doc -man \
> + $ tools/doc/kernel-doc -man \
> $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
> | scripts/split-man.pl /tmp/man
>
> - $ scripts/kernel-doc -man \
> + $ tools/doc/kernel-doc -man \
> $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
> | scripts/split-man.pl /tmp/man
>
> diff --git a/Documentation/translations/zh_CN/kbuild/kbuild.rst b/Documentation/translations/zh_CN/kbuild/kbuild.rst
> index e5e2aebe1ebc..3650a48a8db6 100644
> --- a/Documentation/translations/zh_CN/kbuild/kbuild.rst
> +++ b/Documentation/translations/zh_CN/kbuild/kbuild.rst
> @@ -158,7 +158,7 @@ UTS_MACHINE 变量（在某些架构中还包括内核配置）来猜测正确
> KDOCFLAGS
> ---------
> 指定在构建过程中用于 kernel-doc 检查的额外（警告/错误）标志，查看
> -scripts/kernel-doc 了解支持的标志。请注意，这目前不适用于文档构建。
> +tools/doc/kernel-doc 了解支持的标志。请注意，这目前不适用于文档构建。
>
> ARCH
> ----
> diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst
> index 0484d0c65c25..64f0c13ff831 100644
> --- a/Documentation/translations/zh_CN/process/coding-style.rst
> +++ b/Documentation/translations/zh_CN/process/coding-style.rst
> @@ -545,7 +545,7 @@ Linux 里这是提倡的做法，因为这样可以很简单的给读者提供
> 也可以加上它做这些事情的原因。
>
> 当注释内核 API 函数时，请使用 kernel-doc 格式。详见
> -Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。
> +Documentation/translations/zh_CN/doc-guide/index.rst 和 tools/doc/kernel-doc 。
>
> 长 (多行) 注释的首选风格是：
>
> diff --git a/Documentation/translations/zh_TW/process/coding-style.rst b/Documentation/translations/zh_TW/process/coding-style.rst
> index 311c6f6bad0b..1e9dee6bbdd0 100644
> --- a/Documentation/translations/zh_TW/process/coding-style.rst
> +++ b/Documentation/translations/zh_TW/process/coding-style.rst
> @@ -548,7 +548,7 @@ Linux 裏這是提倡的做法，因爲這樣可以很簡單的給讀者提供
> 也可以加上它做這些事情的原因。
>
> 當註釋內核 API 函數時，請使用 kernel-doc 格式。詳見
> -Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。
> +Documentation/translations/zh_CN/doc-guide/index.rst 和 tools/doc/kernel-doc 。
>
> 長 (多行) 註釋的首選風格是：
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index c2d2ce92bf79..0fa427577f15 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -7302,7 +7302,6 @@ P: Documentation/doc-guide/maintainer-profile.rst
> T: git git://git.lwn.net/linux.git docs-next
> F: Documentation/
> F: tools/doc/
> -F: scripts/kernel-doc*
> F: scripts/lib/abi/*
> F: scripts/lib/kdoc/*
> F: tools/net/ynl/pyynl/lib/doc_generator.py
> diff --git a/Makefile b/Makefile
> index 6bfe776bf3c5..44577bd357bb 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -460,7 +460,7 @@ HOSTPKG_CONFIG = pkg-config
>
> # 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/doc/kernel-doc.py
> export KERNELDOC
>
> KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \
> diff --git a/drivers/gpu/drm/i915/Makefile b/drivers/gpu/drm/i915/Makefile
> index 853543443072..6e732e0079c1 100644
> --- a/drivers/gpu/drm/i915/Makefile
> +++ b/drivers/gpu/drm/i915/Makefile
> @@ -426,7 +426,7 @@ always-$(CONFIG_DRM_I915_WERROR) += \
>
> 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 $@
> + $(srctree)/tools/doc/kernel-doc -none -Werror $<; touch $@
>
> $(obj)/%.hdrtest: $(src)/%.h FORCE
> $(call if_changed_dep,hdrtest)
> diff --git a/scripts/find-unused-docs.sh b/scripts/find-unused-docs.sh
> index d6d397fbf917..0ae445dec2e4 100755
> --- a/scripts/find-unused-docs.sh
> +++ b/scripts/find-unused-docs.sh
> @@ -54,7 +54,7 @@ for file in `find $1 -name '*.c'`; do
> if [[ ${FILES_INCLUDED[$file]+_} ]]; then
> continue;
> fi
> - str=$(PYTHONDONTWRITEBYTECODE=1 scripts/kernel-doc -export "$file" 2>/dev/null)
> + str=$(PYTHONDONTWRITEBYTECODE=1 tools/doc/kernel-doc -export "$file" 2>/dev/null)
> if [[ -n "$str" ]]; then
> echo "$file"
> fi
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> deleted file mode 120000
> index 3b6ef807791a..000000000000
> --- a/scripts/kernel-doc
> +++ /dev/null
> @@ -1 +0,0 @@
> -kernel-doc.py
> \ No newline at end of file
> diff --git a/scripts/kernel-doc.py b/tools/doc/kernel-doc
> similarity index 100%
> rename from scripts/kernel-doc.py
> rename to tools/doc/kernel-doc
Thanks,
Mauro
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 07/13] docs: move sphinx-pre-install to tools/doc
2025-08-13 21:32 ` [PATCH 07/13] docs: move sphinx-pre-install " Jonathan Corbet
@ 2025-08-13 23:36 ` Mauro Carvalho Chehab
2025-08-14 2:14 ` Jonathan Corbet
0 siblings, 1 reply; 47+ messages in thread
From: Mauro Carvalho Chehab @ 2025-08-13 23:36 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Akira Yokosawa, Randy Dunlap
Em Wed, 13 Aug 2025 15:32:06 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> Put this tool with the other documentation-related scripts.
This one will be painful, as it will cause conflicts with my series
that clean up the docs Makefile.
>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
> Documentation/Makefile | 14 +++++++-------
> Documentation/doc-guide/sphinx.rst | 4 ++--
> Documentation/sphinx/kerneldoc-preamble.sty | 2 +-
> .../translations/it_IT/doc-guide/sphinx.rst | 4 ++--
> .../translations/zh_CN/doc-guide/sphinx.rst | 4 ++--
> Documentation/translations/zh_CN/how-to.rst | 2 +-
> MAINTAINERS | 2 --
> {scripts => tools/doc}/sphinx-pre-install | 0
> 8 files changed, 15 insertions(+), 17 deletions(-)
> rename {scripts => tools/doc}/sphinx-pre-install (100%)
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index eef5decb79b8..818d866756b0 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -46,7 +46,7 @@ ifeq ($(HAVE_SPHINX),0)
> .DEFAULT:
> $(warning The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed and in PATH, or set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable.)
> @echo
> - @$(srctree)/scripts/sphinx-pre-install
> + @$(srctree)/tools/doc/sphinx-pre-install
> @echo " SKIP Sphinx $@ target."
>
> else # HAVE_SPHINX
> @@ -105,7 +105,7 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
> fi
>
> htmldocs:
> - @$(srctree)/scripts/sphinx-pre-install --version-check
> + @$(srctree)/tools/doc/sphinx-pre-install --version-check
> @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
>
> # If Rust support is available and .config exists, add rustdoc generated contents.
> @@ -119,7 +119,7 @@ endif
> endif
>
> texinfodocs:
> - @$(srctree)/scripts/sphinx-pre-install --version-check
> + @$(srctree)/tools/doc/sphinx-pre-install --version-check
> @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,texinfo,$(var),texinfo,$(var)))
>
> # Note: the 'info' Make target is generated by sphinx itself when
> @@ -131,7 +131,7 @@ linkcheckdocs:
> @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
>
> latexdocs:
> - @$(srctree)/scripts/sphinx-pre-install --version-check
> + @$(srctree)/tools/doc/sphinx-pre-install --version-check
> @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))
>
> ifeq ($(HAVE_PDFLATEX),0)
> @@ -144,7 +144,7 @@ else # HAVE_PDFLATEX
>
> pdfdocs: DENY_VF = XDG_CONFIG_HOME=$(FONTS_CONF_DENY_VF)
> pdfdocs: latexdocs
> - @$(srctree)/scripts/sphinx-pre-install --version-check
> + @$(srctree)/tools/doc/sphinx-pre-install --version-check
> $(foreach var,$(SPHINXDIRS), \
> $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" $(DENY_VF) -C $(BUILDDIR)/$(var)/latex || sh $(srctree)/tools/doc/check-variable-fonts.sh || exit; \
> mkdir -p $(BUILDDIR)/$(var)/pdf; \
> @@ -154,11 +154,11 @@ pdfdocs: latexdocs
> endif # HAVE_PDFLATEX
>
> epubdocs:
> - @$(srctree)/scripts/sphinx-pre-install --version-check
> + @$(srctree)/tools/doc/sphinx-pre-install --version-check
> @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))
>
> xmldocs:
> - @$(srctree)/scripts/sphinx-pre-install --version-check
> + @$(srctree)/tools/doc/sphinx-pre-install --version-check
> @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var)))
>
> endif # HAVE_SPHINX
> diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
> index 607589592bfb..2a0fc6c39cf4 100644
> --- a/Documentation/doc-guide/sphinx.rst
> +++ b/Documentation/doc-guide/sphinx.rst
> @@ -106,7 +106,7 @@ There's a script that automatically checks for Sphinx dependencies. If it can
> recognize your distribution, it will also give a hint about the install
> command line options for your distro::
>
> - $ ./scripts/sphinx-pre-install
> + $ ./tools/doc/sphinx-pre-install
> Checking if the needed tools for Fedora release 26 (Twenty Six) are available
> Warning: better to also install "texlive-luatex85".
> You should run:
> @@ -116,7 +116,7 @@ command line options for your distro::
> . sphinx_2.4.4/bin/activate
> pip install -r Documentation/sphinx/requirements.txt
>
> - Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
> + Can't build as 1 mandatory dependency is missing at ./tools/doc/sphinx-pre-install line 468.
>
> By default, it checks all the requirements for both html and PDF, including
> the requirements for images, math expressions and LaTeX build, and assumes
> diff --git a/Documentation/sphinx/kerneldoc-preamble.sty b/Documentation/sphinx/kerneldoc-preamble.sty
> index 5d68395539fe..736c2568377e 100644
> --- a/Documentation/sphinx/kerneldoc-preamble.sty
> +++ b/Documentation/sphinx/kerneldoc-preamble.sty
> @@ -220,7 +220,7 @@
> If you want them, please install non-variable ``Noto Sans CJK''
> font families along with the texlive-xecjk package by following
> instructions from
> - \sphinxcode{./scripts/sphinx-pre-install}.
> + \sphinxcode{./tools/doc/sphinx-pre-install}.
> Having optional non-variable ``Noto Serif CJK'' font families will
> improve the looks of those translations.
> \end{sphinxadmonition}}
> diff --git a/Documentation/translations/it_IT/doc-guide/sphinx.rst b/Documentation/translations/it_IT/doc-guide/sphinx.rst
> index 1f513bc33618..104aa159c1ce 100644
> --- a/Documentation/translations/it_IT/doc-guide/sphinx.rst
> +++ b/Documentation/translations/it_IT/doc-guide/sphinx.rst
> @@ -109,7 +109,7 @@ Sphinx. Se lo script riesce a riconoscere la vostra distribuzione, allora
> sarà in grado di darvi dei suggerimenti su come procedere per completare
> l'installazione::
>
> - $ ./scripts/sphinx-pre-install
> + $ ./tools/doc/sphinx-pre-install
> Checking if the needed tools for Fedora release 26 (Twenty Six) are available
> Warning: better to also install "texlive-luatex85".
> You should run:
> @@ -119,7 +119,7 @@ l'installazione::
> . sphinx_2.4.4/bin/activate
> pip install -r Documentation/sphinx/requirements.txt
>
> - Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
> + Can't build as 1 mandatory dependency is missing at ./tools/doc/sphinx-pre-install line 468.
>
> L'impostazione predefinita prevede il controllo dei requisiti per la generazione
> di documenti html e PDF, includendo anche il supporto per le immagini, le
> diff --git a/Documentation/translations/zh_CN/doc-guide/sphinx.rst b/Documentation/translations/zh_CN/doc-guide/sphinx.rst
> index 23eac67fbc30..3d2c4e262bb5 100644
> --- a/Documentation/translations/zh_CN/doc-guide/sphinx.rst
> +++ b/Documentation/translations/zh_CN/doc-guide/sphinx.rst
> @@ -84,7 +84,7 @@ PDF和LaTeX构建
> 这有一个脚本可以自动检查Sphinx依赖项。如果它认得您的发行版，还会提示您所用发行
> 版的安装命令::
>
> - $ ./scripts/sphinx-pre-install
> + $ ./tools/doc/sphinx-pre-install
> Checking if the needed tools for Fedora release 26 (Twenty Six) are available
> Warning: better to also install "texlive-luatex85".
> You should run:
> @@ -94,7 +94,7 @@ PDF和LaTeX构建
> . sphinx_2.4.4/bin/activate
> pip install -r Documentation/sphinx/requirements.txt
>
> - Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
> + Can't build as 1 mandatory dependency is missing at ./tools/doc/sphinx-pre-install line 468.
>
> 默认情况下，它会检查html和PDF的所有依赖项，包括图像、数学表达式和LaTeX构建的
> 需求，并假设将使用虚拟Python环境。html构建所需的依赖项被认为是必需的，其他依
> diff --git a/Documentation/translations/zh_CN/how-to.rst b/Documentation/translations/zh_CN/how-to.rst
> index cf66c72ee0c5..77da507d29cf 100644
> --- a/Documentation/translations/zh_CN/how-to.rst
> +++ b/Documentation/translations/zh_CN/how-to.rst
> @@ -64,7 +64,7 @@ Linux 发行版和简单地使用 Linux 命令行，那么可以迅速开始了
> ::
>
> cd linux
> - ./scripts/sphinx-pre-install
> + ./tools/doc/sphinx-pre-install
>
> 以 Fedora 为例，它的输出是这样的::
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index b41b78215035..2f1374130240 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -7306,7 +7306,6 @@ F: scripts/kernel-doc*
> F: scripts/lib/abi/*
> F: scripts/lib/kdoc/*
> F: tools/net/ynl/pyynl/lib/doc_generator.py
> -F: scripts/sphinx-pre-install
> X: Documentation/ABI/
> X: Documentation/admin-guide/media/
> X: Documentation/devicetree/
> @@ -7341,7 +7340,6 @@ L: linux-doc@vger.kernel.org
> S: Maintained
> F: Documentation/sphinx/parse-headers.pl
> F: tools/doc/
> -F: scripts/sphinx-pre-install
>
> DOCUMENTATION/ITALIAN
> M: Federico Vaga <federico.vaga@vaga.pv.it>
> diff --git a/scripts/sphinx-pre-install b/tools/doc/sphinx-pre-install
> similarity index 100%
> rename from scripts/sphinx-pre-install
> rename to tools/doc/sphinx-pre-install
Thanks,
Mauro
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 08/13] docs: move test_doc_build.py to tools/doc
2025-08-13 21:32 ` [PATCH 08/13] docs: move test_doc_build.py " Jonathan Corbet
@ 2025-08-13 23:36 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 47+ messages in thread
From: Mauro Carvalho Chehab @ 2025-08-13 23:36 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Akira Yokosawa, Randy Dunlap
Em Wed, 13 Aug 2025 15:32:07 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> Add this tool to tools/doc.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
> Documentation/doc-guide/sphinx.rst | 2 +-
> {scripts => tools/doc}/test_doc_build.py | 0
> 2 files changed, 1 insertion(+), 1 deletion(-)
> rename {scripts => tools/doc}/test_doc_build.py (100%)
>
> diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
> index 2a0fc6c39cf4..d874dd0ed7d0 100644
> --- a/Documentation/doc-guide/sphinx.rst
> +++ b/Documentation/doc-guide/sphinx.rst
> @@ -149,7 +149,7 @@ a venv with it with, and install minimal requirements with::
>
> A more comprehensive test can be done by using:
>
> - scripts/test_doc_build.py
> + tools/doc/test_doc_build.py
>
> Such script create one Python venv per supported version,
> optionally building documentation for a range of Sphinx versions.
> diff --git a/scripts/test_doc_build.py b/tools/doc/test_doc_build.py
> similarity index 100%
> rename from scripts/test_doc_build.py
> rename to tools/doc/test_doc_build.py
Thanks,
Mauro
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 01/13] docs: Move the "features" tools to tools/doc
2025-08-13 21:32 ` [PATCH 01/13] docs: Move the "features" tools to tools/doc Jonathan Corbet
@ 2025-08-13 23:38 ` Mauro Carvalho Chehab
2025-08-13 23:42 ` Randy Dunlap
0 siblings, 1 reply; 47+ messages in thread
From: Mauro Carvalho Chehab @ 2025-08-13 23:38 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Akira Yokosawa, Randy Dunlap
Em Wed, 13 Aug 2025 15:32:00 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> The scripts for managing the features docs are found in three different
> directories; unite them all under tools/doc and update references as
> needed.
>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
> Documentation/sphinx/kernel_feat.py | 4 ++--
> .../features/scripts => tools/doc}/features-refresh.sh | 0
> {scripts => tools/doc}/get_feat.pl | 2 +-
This one is the next on my list to convert to Python, but I didn't
do any changes on it yet.
So,
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> {Documentation/features => tools/doc}/list-arch.sh | 2 +-
> 4 files changed, 4 insertions(+), 4 deletions(-)
> rename {Documentation/features/scripts => tools/doc}/features-refresh.sh (100%)
> rename {scripts => tools/doc}/get_feat.pl (99%)
> rename {Documentation/features => tools/doc}/list-arch.sh (83%)
I wonder if the best wouldn't be to have a single script for
features handling all usecases.
>
> diff --git a/Documentation/sphinx/kernel_feat.py b/Documentation/sphinx/kernel_feat.py
> index e3a51867f27b..5453a7b1fc9f 100644
> --- a/Documentation/sphinx/kernel_feat.py
> +++ b/Documentation/sphinx/kernel_feat.py
> @@ -13,7 +13,7 @@
> :license: GPL Version 2, June 1991 see Linux/COPYING for details.
>
> The ``kernel-feat`` (:py:class:`KernelFeat`) directive calls the
> - scripts/get_feat.pl script to parse the Kernel ABI files.
> + tools/doc/get_feat.pl script to parse the Kernel ABI files.
>
> Overview of directive's argument and options.
>
> @@ -83,7 +83,7 @@ class KernelFeat(Directive):
> srctree = os.path.abspath(os.environ["srctree"])
>
> args = [
> - os.path.join(srctree, 'scripts/get_feat.pl'),
> + os.path.join(srctree, 'tools/doc/get_feat.pl'),
> 'rest',
> '--enable-fname',
> '--dir',
> diff --git a/Documentation/features/scripts/features-refresh.sh b/tools/doc/features-refresh.sh
> similarity index 100%
> rename from Documentation/features/scripts/features-refresh.sh
> rename to tools/doc/features-refresh.sh
> diff --git a/scripts/get_feat.pl b/tools/doc/get_feat.pl
> similarity index 99%
> rename from scripts/get_feat.pl
> rename to tools/doc/get_feat.pl
> index 40fb28c8424e..d75e7c85dc85 100755
> --- a/scripts/get_feat.pl
> +++ b/tools/doc/get_feat.pl
> @@ -18,7 +18,7 @@ my $enable_fname;
> my $basename = abs_path($0);
> $basename =~ s,/[^/]+$,/,;
>
> -my $prefix=$basename . "../Documentation/features";
> +my $prefix=$basename . "../../Documentation/features";
>
> # Used only at for full features output. The script will auto-adjust
> # such values for the minimal possible values
> diff --git a/Documentation/features/list-arch.sh b/tools/doc/list-arch.sh
> similarity index 83%
> rename from Documentation/features/list-arch.sh
> rename to tools/doc/list-arch.sh
> index ac8ff7f6f859..96fe83b7058b 100755
> --- a/Documentation/features/list-arch.sh
> +++ b/tools/doc/list-arch.sh
> @@ -8,4 +8,4 @@
>
> ARCH=${1:-$(uname -m | sed 's/x86_64/x86/' | sed 's/i386/x86/' | sed 's/s390x/s390/')}
>
> -$(dirname $0)/../../scripts/get_feat.pl list --arch $ARCH
> +$(dirname $0)/get_feat.pl list --arch $ARCH
Thanks,
Mauro
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 01/13] docs: Move the "features" tools to tools/doc
2025-08-13 23:38 ` Mauro Carvalho Chehab
@ 2025-08-13 23:42 ` Randy Dunlap
2025-08-14 5:56 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 47+ messages in thread
From: Randy Dunlap @ 2025-08-13 23:42 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Jonathan Corbet
Cc: linux-doc, linux-kernel, Akira Yokosawa
On 8/13/25 4:38 PM, Mauro Carvalho Chehab wrote:
> Em Wed, 13 Aug 2025 15:32:00 -0600
> Jonathan Corbet <corbet@lwn.net> escreveu:
>
>> The scripts for managing the features docs are found in three different
>> directories; unite them all under tools/doc and update references as
>> needed.
>>
>> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
>> ---
>> Documentation/sphinx/kernel_feat.py | 4 ++--
>> .../features/scripts => tools/doc}/features-refresh.sh | 0
>> {scripts => tools/doc}/get_feat.pl | 2 +-
>
> This one is the next on my list to convert to Python, but I didn't
> do any changes on it yet.
Just curious, why does it need to be converted from shell to Python?
I'm sure you will explain that in the patch description (or cover letter).
> So,
>
> Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>
>
>> {Documentation/features => tools/doc}/list-arch.sh | 2 +-
>> 4 files changed, 4 insertions(+), 4 deletions(-)
>> rename {Documentation/features/scripts => tools/doc}/features-refresh.sh (100%)
>> rename {scripts => tools/doc}/get_feat.pl (99%)
>> rename {Documentation/features => tools/doc}/list-arch.sh (83%)
>
> I wonder if the best wouldn't be to have a single script for
> features handling all usecases.
--
~Randy
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 06/13] docs: move get_abi.py to tools/doc
2025-08-13 21:32 ` [PATCH 06/13] docs: move get_abi.py to tools/doc Jonathan Corbet
@ 2025-08-13 23:43 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 47+ messages in thread
From: Mauro Carvalho Chehab @ 2025-08-13 23:43 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Akira Yokosawa, Randy Dunlap
Em Wed, 13 Aug 2025 15:32:05 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> Move this tool out of scripts/ to join the other documentation tools; fix
> up a couple of erroneous references in the process.
>
> It's worth noting that this script will fail badly unless one has a
> PYTHONPATH referencing scripts/lib/abi.
Heh, on all Python scripts you're moving, you need to change the logic.
In the case of kernel-doc, you need to change from:
LIB_DIR = "lib/kdoc"
SRC_DIR = os.path.dirname(os.path.realpath(__file__)) # Currently scripts/
sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR))
to:
LIB_DIR = "../../scripts/lib/kdoc"
SRC_DIR = os.path.dirname(os.path.realpath(__file__)) # Currently scripts/
sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR))
Here, it is the same, except that LIB_DIR will now be:
LIB_DIR = "../../scripts/lib/abi"
>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
> Documentation/Kconfig | 2 +-
> Documentation/Makefile | 2 +-
> Documentation/sphinx/kernel_abi.py | 2 +-
> MAINTAINERS | 1 -
> {scripts => tools/doc}/get_abi.py | 0
> 5 files changed, 3 insertions(+), 4 deletions(-)
> rename {scripts => tools/doc}/get_abi.py (100%)
>
> diff --git a/Documentation/Kconfig b/Documentation/Kconfig
> index 3a0e7ac0c4e3..70178e9e0c6c 100644
> --- a/Documentation/Kconfig
> +++ b/Documentation/Kconfig
> @@ -19,7 +19,7 @@ config WARN_ABI_ERRORS
> described at Documentation/ABI/README. Yet, as they're manually
> written, it would be possible that some of those files would
> have errors that would break them for being parsed by
> - scripts/get_abi.pl. Add a check to verify them.
> + tools/doc/get_abi.py. Add a check to verify them.
>
> If unsure, select 'N'.
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 962c4fab94b0..eef5decb79b8 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -13,7 +13,7 @@ endif
>
> # Check for broken ABI files
> ifeq ($(CONFIG_WARN_ABI_ERRORS),y)
> -$(shell $(srctree)/scripts/get_abi.py --dir $(srctree)/Documentation/ABI validate)
> +$(shell $(srctree)/tools/doc/get_abi.py --dir $(srctree)/Documentation/ABI validate)
> endif
> endif
>
> diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
> index 4c4375201b9e..32e39fb8bc3b 100644
> --- a/Documentation/sphinx/kernel_abi.py
> +++ b/Documentation/sphinx/kernel_abi.py
> @@ -14,7 +14,7 @@
> :license: GPL Version 2, June 1991 see Linux/COPYING for details.
>
> The ``kernel-abi`` (:py:class:`KernelCmd`) directive calls the
> - scripts/get_abi.py script to parse the Kernel ABI files.
> + AbiParser class to parse the Kernel ABI files.
>
> Overview of directive's argument and options.
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index ec9872642597..b41b78215035 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -7302,7 +7302,6 @@ P: Documentation/doc-guide/maintainer-profile.rst
> T: git git://git.lwn.net/linux.git docs-next
> F: Documentation/
> F: tools/doc/
> -F: scripts/get_abi.py
> F: scripts/kernel-doc*
> F: scripts/lib/abi/*
> F: scripts/lib/kdoc/*
> diff --git a/scripts/get_abi.py b/tools/doc/get_abi.py
> similarity index 100%
> rename from scripts/get_abi.py
> rename to tools/doc/get_abi.py
Thanks,
Mauro
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 03/13] docs: move scripts/check-variable-fonts.sh to tools/doc
2025-08-13 21:32 ` [PATCH 03/13] docs: move scripts/check-variable-fonts.sh " Jonathan Corbet
@ 2025-08-13 23:46 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 47+ messages in thread
From: Mauro Carvalho Chehab @ 2025-08-13 23:46 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Akira Yokosawa, Randy Dunlap
Em Wed, 13 Aug 2025 15:32:02 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> Move this script to live with the rest of the documentation tools.
This one will also be obsoleted with the new sphinx-build-wrapper tool.
Please don't touch on it yet.
>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
> Documentation/Makefile | 2 +-
> MAINTAINERS | 1 -
> {scripts => tools/doc}/check-variable-fonts.sh | 2 +-
> 3 files changed, 2 insertions(+), 3 deletions(-)
> rename {scripts => tools/doc}/check-variable-fonts.sh (98%)
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 820f07e0afe6..70095465dce1 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -146,7 +146,7 @@ pdfdocs: DENY_VF = XDG_CONFIG_HOME=$(FONTS_CONF_DENY_VF)
> pdfdocs: latexdocs
> @$(srctree)/scripts/sphinx-pre-install --version-check
> $(foreach var,$(SPHINXDIRS), \
> - $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" $(DENY_VF) -C $(BUILDDIR)/$(var)/latex || sh $(srctree)/scripts/check-variable-fonts.sh || exit; \
> + $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" $(DENY_VF) -C $(BUILDDIR)/$(var)/latex || sh $(srctree)/tools/doc/check-variable-fonts.sh || exit; \
> mkdir -p $(BUILDDIR)/$(var)/pdf; \
> mv $(subst .tex,.pdf,$(wildcard $(BUILDDIR)/$(var)/latex/*.tex)) $(BUILDDIR)/$(var)/pdf/; \
> )
> diff --git a/MAINTAINERS b/MAINTAINERS
> index a3a396fc1c3f..ca4c7992369d 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -7302,7 +7302,6 @@ P: Documentation/doc-guide/maintainer-profile.rst
> T: git git://git.lwn.net/linux.git docs-next
> F: Documentation/
> F: tools/doc/
> -F: scripts/check-variable-fonts.sh
> F: scripts/documentation-file-ref-check
> F: scripts/get_abi.py
> F: scripts/kernel-doc*
> diff --git a/scripts/check-variable-fonts.sh b/tools/doc/check-variable-fonts.sh
> similarity index 98%
> rename from scripts/check-variable-fonts.sh
> rename to tools/doc/check-variable-fonts.sh
> index ce63f0acea5f..9660df53d716 100755
> --- a/scripts/check-variable-fonts.sh
> +++ b/tools/doc/check-variable-fonts.sh
> @@ -106,7 +106,7 @@ if [ "x$notocjkvffonts" != "x" ] ; then
> echo 'Or, CJK pages can be skipped by uninstalling texlive-xecjk.'
> echo
> echo 'For more info on denylisting, other options, and variable font, see header'
> - echo 'comments of scripts/check-variable-fonts.sh.'
> + echo 'comments of tools/doc/check-variable-fonts.sh.'
> echo '============================================================================='
> fi
>
Thanks,
Mauro
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 04/13] docs: move scripts/documentation-file-ref-check to tools/doc
2025-08-13 21:32 ` [PATCH 04/13] docs: move scripts/documentation-file-ref-check " Jonathan Corbet
@ 2025-08-13 23:47 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 47+ messages in thread
From: Mauro Carvalho Chehab @ 2025-08-13 23:47 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Akira Yokosawa, Randy Dunlap
Em Wed, 13 Aug 2025 15:32:03 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> Add this script to the growing collection of documentation tools.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
> Documentation/Makefile | 4 ++--
> MAINTAINERS | 3 +--
> scripts/sphinx-pre-install | 2 +-
> {scripts => tools/doc}/documentation-file-ref-check | 2 +-
> 4 files changed, 5 insertions(+), 6 deletions(-)
> rename {scripts => tools/doc}/documentation-file-ref-check (99%)
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 70095465dce1..f7b8342f9666 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -8,7 +8,7 @@ subdir- := devicetree/bindings
> ifneq ($(MAKECMDGOALS),cleandocs)
> # Check for broken documentation file references
> ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y)
> -$(shell $(srctree)/scripts/documentation-file-ref-check --warn)
> +$(shell $(srctree)/tools/doc/documentation-file-ref-check --warn)
> endif
>
> # Check for broken ABI files
> @@ -167,7 +167,7 @@ endif # HAVE_SPHINX
> # work or silently pass without Sphinx.
>
> refcheckdocs:
> - $(Q)cd $(srctree);scripts/documentation-file-ref-check
> + $(Q)cd $(srctree); tools/doc/documentation-file-ref-check
>
> cleandocs:
> $(Q)rm -rf $(BUILDDIR)
> diff --git a/MAINTAINERS b/MAINTAINERS
> index ca4c7992369d..ec9872642597 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -7302,7 +7302,6 @@ P: Documentation/doc-guide/maintainer-profile.rst
> T: git git://git.lwn.net/linux.git docs-next
> F: Documentation/
> F: tools/doc/
> -F: scripts/documentation-file-ref-check
> F: scripts/get_abi.py
> F: scripts/kernel-doc*
> F: scripts/lib/abi/*
> @@ -7342,7 +7341,7 @@ M: Mauro Carvalho Chehab <mchehab@kernel.org>
> L: linux-doc@vger.kernel.org
> S: Maintained
> F: Documentation/sphinx/parse-headers.pl
> -F: scripts/documentation-file-ref-check
> +F: tools/doc/
> F: scripts/sphinx-pre-install
>
> DOCUMENTATION/ITALIAN
> diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
> index b8474848df4e..5d006a037428 100755
> --- a/scripts/sphinx-pre-install
> +++ b/scripts/sphinx-pre-install
> @@ -406,7 +406,7 @@ class MissingCheckers(AncillaryMethods):
> Right now, we still need Perl for doc build, as it is required
> by some tools called at docs or kernel build time, like:
>
> - scripts/documentation-file-ref-check
> + tools/doc/documentation-file-ref-check
>
> Also, checkpatch is on Perl.
> """
> diff --git a/scripts/documentation-file-ref-check b/tools/doc/documentation-file-ref-check
> similarity index 99%
> rename from scripts/documentation-file-ref-check
> rename to tools/doc/documentation-file-ref-check
> index 408b1dbe7884..2dc53f5661b1 100755
> --- a/scripts/documentation-file-ref-check
> +++ b/tools/doc/documentation-file-ref-check
> @@ -17,7 +17,7 @@ my %false_positives = (
> );
>
> my $scriptname = $0;
> -$scriptname =~ s,.*/([^/]+/),$1,;
> +$scriptname =~ s,tools/doc/([^/]+/),$1,;
>
> # Parse arguments
> my $help = 0;
Thanks,
Mauro
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 10/13] docs: move kernel-doc to tools/doc
2025-08-13 21:32 ` [PATCH 10/13] docs: move kernel-doc " Jonathan Corbet
2025-08-13 23:33 ` Mauro Carvalho Chehab
@ 2025-08-13 23:48 ` Mauro Carvalho Chehab
2025-08-14 12:13 ` kernel test robot
2 siblings, 0 replies; 47+ messages in thread
From: Mauro Carvalho Chehab @ 2025-08-13 23:48 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Akira Yokosawa, Randy Dunlap
Em Wed, 13 Aug 2025 15:32:09 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> deleted file mode 120000
> index 3b6ef807791a..000000000000
> --- a/scripts/kernel-doc
> +++ /dev/null
> @@ -1 +0,0 @@
> -kernel-doc.py
> \ No newline at end of file
> diff --git a/scripts/kernel-doc.py b/tools/doc/kernel-doc
> similarity index 100%
> rename from scripts/kernel-doc.py
> rename to tools/doc/kernel-doc
Heh, this is not right: you forgot to update LIB_DIR. if you do that,
you'll break the script. See my comments to get_abi.py.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 11/13] docs: move split-man.pl to tools/doc
2025-08-13 21:32 ` [PATCH 11/13] docs: move split-man.pl " Jonathan Corbet
@ 2025-08-13 23:50 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 47+ messages in thread
From: Mauro Carvalho Chehab @ 2025-08-13 23:50 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Akira Yokosawa, Randy Dunlap
Em Wed, 13 Aug 2025 15:32:10 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> ...and update all references to it.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Btw, I was not aware of this. It makes sense to move its logic to
the new sphinx-build-wrapper Python script that I'll be submitting
soon.
>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
> Documentation/doc-guide/kernel-doc.rst | 6 +++---
> Documentation/translations/it_IT/doc-guide/kernel-doc.rst | 2 +-
> Documentation/translations/zh_CN/doc-guide/kernel-doc.rst | 6 +++---
> {scripts => tools/doc}/split-man.pl | 0
> 4 files changed, 7 insertions(+), 7 deletions(-)
> rename {scripts => tools/doc}/split-man.pl (100%)
>
> diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
> index 6fc89d444ada..b7c8ce55323c 100644
> --- a/Documentation/doc-guide/kernel-doc.rst
> +++ b/Documentation/doc-guide/kernel-doc.rst
> @@ -584,15 +584,15 @@ from the kernel git tree::
>
> $ tools/doc/kernel-doc -man \
> $(git grep -l '/\*\*' -- :^Documentation :^tools) \
> - | scripts/split-man.pl /tmp/man
> + | tools/doc/split-man.pl /tmp/man
>
> Some older versions of git do not support some of the variants of syntax for
> path exclusion. One of the following commands may work for those versions::
>
> $ tools/doc/kernel-doc -man \
> $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
> - | scripts/split-man.pl /tmp/man
> + | tools/doc/split-man.pl /tmp/man
>
> $ tools/doc/kernel-doc -man \
> $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
> - | scripts/split-man.pl /tmp/man
> + | tools/doc/split-man.pl /tmp/man
> diff --git a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
> index 05ea0f03c80b..bf04ceea2d83 100644
> --- a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
> +++ b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
> @@ -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::
>
> - $ tools/doc/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man
> + $ tools/doc/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | tools/doc/split-man.pl /tmp/man
> diff --git a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
> index b242e52f911c..a807295bc403 100644
> --- a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
> +++ b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
> @@ -484,16 +484,16 @@ kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/k
>
> $ tools/doc/kernel-doc -man \
> $(git grep -l '/\*\*' -- :^Documentation :^tools) \
> - | scripts/split-man.pl /tmp/man
> + | tools/doc/split-man.pl /tmp/man
>
> 一些旧版本的git不支持路径排除语法的某些变体。
> 以下命令之一可能适用于这些版本::
>
> $ tools/doc/kernel-doc -man \
> $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
> - | scripts/split-man.pl /tmp/man
> + | tools/doc/split-man.pl /tmp/man
>
> $ tools/doc/kernel-doc -man \
> $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
> - | scripts/split-man.pl /tmp/man
> + | tools/doc/split-man.pl /tmp/man
>
> diff --git a/scripts/split-man.pl b/tools/doc/split-man.pl
> similarity index 100%
> rename from scripts/split-man.pl
> rename to tools/doc/split-man.pl
Thanks,
Mauro
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 12/13] docs: move find-unused-docs.sh to tools/doc
2025-08-13 21:32 ` [PATCH 12/13] docs: move find-unused-docs.sh " Jonathan Corbet
@ 2025-08-13 23:50 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 47+ messages in thread
From: Mauro Carvalho Chehab @ 2025-08-13 23:50 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Akira Yokosawa, Randy Dunlap
Em Wed, 13 Aug 2025 15:32:11 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> ...and update references accordingly.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
> Documentation/doc-guide/contributing.rst | 2 +-
> Documentation/translations/zh_CN/doc-guide/contributing.rst | 2 +-
> {scripts => tools/doc}/find-unused-docs.sh | 6 +++---
> 3 files changed, 5 insertions(+), 5 deletions(-)
> rename {scripts => tools/doc}/find-unused-docs.sh (85%)
>
> diff --git a/Documentation/doc-guide/contributing.rst b/Documentation/doc-guide/contributing.rst
> index 662c7a840cd5..81633c6c6c11 100644
> --- a/Documentation/doc-guide/contributing.rst
> +++ b/Documentation/doc-guide/contributing.rst
> @@ -152,7 +152,7 @@ generate links to that documentation. Adding ``kernel-doc`` directives to
> the documentation to bring those comments in can help the community derive
> the full value of the work that has gone into creating them.
>
> -The ``scripts/find-unused-docs.sh`` tool can be used to find these
> +The ``tools/doc/find-unused-docs.sh`` tool can be used to find these
> overlooked comments.
>
> Note that the most value comes from pulling in the documentation for
> diff --git a/Documentation/translations/zh_CN/doc-guide/contributing.rst b/Documentation/translations/zh_CN/doc-guide/contributing.rst
> index 394a13b438b0..d205f8ed9fce 100644
> --- a/Documentation/translations/zh_CN/doc-guide/contributing.rst
> +++ b/Documentation/translations/zh_CN/doc-guide/contributing.rst
> @@ -124,7 +124,7 @@ C代码编译器发出的警告常常会被视为误报，从而导致出现了
> 这使得这些信息更难找到，例如使Sphinx无法生成指向该文档的链接。将 ``kernel-doc``
> 指令添加到文档中以引入这些注释可以帮助社区获得为编写注释所做工作的全部价值。
>
> -``scripts/find-unused-docs.sh`` 工具可以用来找到这些被忽略的评论。
> +``tools/doc/find-unused-docs.sh`` 工具可以用来找到这些被忽略的评论。
>
> 请注意，将导出的函数和数据结构引入文档是最有价值的。许多子系统还具有供内部
> 使用的kernel-doc注释；除非这些注释放在专门针对相关子系统开发人员的文档中，
> diff --git a/scripts/find-unused-docs.sh b/tools/doc/find-unused-docs.sh
> similarity index 85%
> rename from scripts/find-unused-docs.sh
> rename to tools/doc/find-unused-docs.sh
> index 0ae445dec2e4..a64389a15f09 100755
> --- a/scripts/find-unused-docs.sh
> +++ b/tools/doc/find-unused-docs.sh
> @@ -5,10 +5,10 @@
> # This script detects files with kernel-doc comments for exported functions
> # that are not included in documentation.
> #
> -# usage: Run 'scripts/find-unused-docs.sh directory' from top level of kernel
> +# usage: Run 'tools/doc/find-unused-docs.sh directory' from top level of kernel
> # tree.
> #
> -# example: $scripts/find-unused-docs.sh drivers/scsi
> +# example: $tools/doc/find-unused-docs.sh drivers/scsi
> #
> # Licensed under the terms of the GNU GPL License
>
> @@ -18,7 +18,7 @@ if ! [ -d "Documentation" ]; then
> fi
>
> if [ "$#" -ne 1 ]; then
> - echo "Usage: scripts/find-unused-docs.sh directory"
> + echo "Usage: tools/doc/find-unused-docs.sh directory"
> exit 1
> fi
>
Thanks,
Mauro
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 02/13] docs: move checktransupdate.py to tools/doc
2025-08-13 21:32 ` [PATCH 02/13] docs: move checktransupdate.py " Jonathan Corbet
@ 2025-08-13 23:51 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 47+ messages in thread
From: Mauro Carvalho Chehab @ 2025-08-13 23:51 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Akira Yokosawa, Randy Dunlap
Em Wed, 13 Aug 2025 15:32:01 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> The checktranslate.py tool currently languishes in scripts/; move it to
> tools/doc and update references accordingly.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
> Documentation/doc-guide/checktransupdate.rst | 6 +++---
> .../translations/zh_CN/doc-guide/checktransupdate.rst | 6 +++---
> Documentation/translations/zh_CN/how-to.rst | 2 +-
> MAINTAINERS | 2 +-
> {scripts => tools/doc}/checktransupdate.py | 8 ++++----
> 5 files changed, 12 insertions(+), 12 deletions(-)
> rename {scripts => tools/doc}/checktransupdate.py (98%)
>
> diff --git a/Documentation/doc-guide/checktransupdate.rst b/Documentation/doc-guide/checktransupdate.rst
> index dfaf9d373747..48bf1ee9a62e 100644
> --- a/Documentation/doc-guide/checktransupdate.rst
> +++ b/Documentation/doc-guide/checktransupdate.rst
> @@ -27,15 +27,15 @@ Usage
>
> ::
>
> - ./scripts/checktransupdate.py --help
> + tools/doc/checktransupdate.py --help
>
> Please refer to the output of argument parser for usage details.
>
> Samples
>
> -- ``./scripts/checktransupdate.py -l zh_CN``
> +- ``tools/doc/checktransupdate.py -l zh_CN``
> This will print all the files that need to be updated in the zh_CN locale.
> -- ``./scripts/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst``
> +- ``tools/doc/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst``
> This will only print the status of the specified file.
>
> Then the output is something like:
> diff --git a/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst b/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
> index d20b4ce66b9f..165e25155084 100644
> --- a/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
> +++ b/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
> @@ -28,15 +28,15 @@
>
> ::
>
> - ./scripts/checktransupdate.py --help
> + tools/doc/checktransupdate.py --help
>
> 具体用法请参考参数解析器的输出
>
> 示例
>
> -- ``./scripts/checktransupdate.py -l zh_CN``
> +- ``tools/doc/checktransupdate.py -l zh_CN``
> 这将打印 zh_CN 语言中需要更新的所有文件。
> -- ``./scripts/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst``
> +- ``tools/doc/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst``
> 这将只打印指定文件的状态。
>
> 然后输出类似如下的内容：
> diff --git a/Documentation/translations/zh_CN/how-to.rst b/Documentation/translations/zh_CN/how-to.rst
> index ddd99c0f9b4d..cf66c72ee0c5 100644
> --- a/Documentation/translations/zh_CN/how-to.rst
> +++ b/Documentation/translations/zh_CN/how-to.rst
> @@ -437,7 +437,7 @@ git email 默认会抄送给您一份，所以您可以切换为审阅者的角
> 对于首次参与 Linux 内核中文文档翻译的新手，建议您在 linux 目录中运行以下命令：
> ::
>
> - ./script/checktransupdate.py -l zh_CN``
> + tools/doc/checktransupdate.py -l zh_CN``
>
> 该命令会列出需要翻译或更新的英文文档，结果同时保存在 checktransupdate.log 中。
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index dafc11712544..a3a396fc1c3f 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -7301,8 +7301,8 @@ S: Maintained
> P: Documentation/doc-guide/maintainer-profile.rst
> T: git git://git.lwn.net/linux.git docs-next
> F: Documentation/
> +F: tools/doc/
> F: scripts/check-variable-fonts.sh
> -F: scripts/checktransupdate.py
> F: scripts/documentation-file-ref-check
> F: scripts/get_abi.py
> F: scripts/kernel-doc*
> diff --git a/scripts/checktransupdate.py b/tools/doc/checktransupdate.py
> similarity index 98%
> rename from scripts/checktransupdate.py
> rename to tools/doc/checktransupdate.py
> index e39529e46c3d..61bd7b02ca55 100755
> --- a/scripts/checktransupdate.py
> +++ b/tools/doc/checktransupdate.py
> @@ -9,9 +9,9 @@ commit to find the latest english commit from the translation commit
> differences occur, report the file and commits that need to be updated.
>
> The usage is as follows:
> -- ./scripts/checktransupdate.py -l zh_CN
> +- tools/doc/checktransupdate.py -l zh_CN
> This will print all the files that need to be updated or translated in the zh_CN locale.
> -- ./scripts/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst
> +- tools/doc/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst
> This will only print the status of the specified file.
>
> The output is something like:
> @@ -168,7 +168,7 @@ def check_per_file(file_path):
> def valid_locales(locale):
> """Check if the locale is valid or not"""
> script_path = os.path.dirname(os.path.abspath(__file__))
> - linux_path = os.path.join(script_path, "..")
> + linux_path = os.path.join(script_path, "../..")
> if not os.path.isdir(f"{linux_path}/Documentation/translations/{locale}"):
> raise ArgumentTypeError("Invalid locale: {locale}")
> return locale
> @@ -232,7 +232,7 @@ def config_logging(log_level, log_file="checktransupdate.log"):
> def main():
> """Main function of the script"""
> script_path = os.path.dirname(os.path.abspath(__file__))
> - linux_path = os.path.join(script_path, "..")
> + linux_path = os.path.join(script_path, "../..")
>
> parser = ArgumentParser(description="Check the translation update")
> parser.add_argument(
Thanks,
Mauro
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 07/13] docs: move sphinx-pre-install to tools/doc
2025-08-13 23:36 ` Mauro Carvalho Chehab
@ 2025-08-14 2:14 ` Jonathan Corbet
2025-08-14 6:21 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 47+ messages in thread
From: Jonathan Corbet @ 2025-08-14 2:14 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: linux-doc, linux-kernel, Akira Yokosawa, Randy Dunlap
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> Em Wed, 13 Aug 2025 15:32:06 -0600
> Jonathan Corbet <corbet@lwn.net> escreveu:
>
>> Put this tool with the other documentation-related scripts.
>
> This one will be painful, as it will cause conflicts with my series
> that clean up the docs Makefile.
Just in general ... I'm more than happy to put this whole series on the
back burner until we've gotten that other stuff merged ... it's an RFC
after all, and there's no urgency here.
jon
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 01/13] docs: Move the "features" tools to tools/doc
2025-08-13 23:42 ` Randy Dunlap
@ 2025-08-14 5:56 ` Mauro Carvalho Chehab
2025-08-14 5:57 ` Randy Dunlap
0 siblings, 1 reply; 47+ messages in thread
From: Mauro Carvalho Chehab @ 2025-08-14 5:56 UTC (permalink / raw)
To: Randy Dunlap; +Cc: Jonathan Corbet, linux-doc, linux-kernel, Akira Yokosawa
Em Wed, 13 Aug 2025 16:42:42 -0700
Randy Dunlap <rdunlap@infradead.org> escreveu:
> On 8/13/25 4:38 PM, Mauro Carvalho Chehab wrote:
> > Em Wed, 13 Aug 2025 15:32:00 -0600
> > Jonathan Corbet <corbet@lwn.net> escreveu:
> >
> >> The scripts for managing the features docs are found in three different
> >> directories; unite them all under tools/doc and update references as
> >> needed.
> >>
> >> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> >> ---
> >> Documentation/sphinx/kernel_feat.py | 4 ++--
> >> .../features/scripts => tools/doc}/features-refresh.sh | 0
> >> {scripts => tools/doc}/get_feat.pl | 2 +-
> >
> > This one is the next on my list to convert to Python, but I didn't
> > do any changes on it yet.
>
> Just curious, why does it need to be converted from shell to Python?
> I'm sure you will explain that in the patch description (or cover letter).
The rationale is the same as kernel-doc and get-abi: there is a Sphinx
extension that executes it. By converting it into Python and splitting
the code into an exec and a library, we can use the library directly at
the extension.
Besides that, the code in Python, specially after using modules and
classes, become IMO clearer, making easier to maintain, specially if
we avoid functions inside functions, complex class inheritance, lamba
functions and multiple statements on a single line.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 01/13] docs: Move the "features" tools to tools/doc
2025-08-14 5:56 ` Mauro Carvalho Chehab
@ 2025-08-14 5:57 ` Randy Dunlap
0 siblings, 0 replies; 47+ messages in thread
From: Randy Dunlap @ 2025-08-14 5:57 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Jonathan Corbet, linux-doc, linux-kernel, Akira Yokosawa
On 8/13/25 10:56 PM, Mauro Carvalho Chehab wrote:
> Em Wed, 13 Aug 2025 16:42:42 -0700
> Randy Dunlap <rdunlap@infradead.org> escreveu:
>
>> On 8/13/25 4:38 PM, Mauro Carvalho Chehab wrote:
>>> Em Wed, 13 Aug 2025 15:32:00 -0600
>>> Jonathan Corbet <corbet@lwn.net> escreveu:
>>>
>>>> The scripts for managing the features docs are found in three different
>>>> directories; unite them all under tools/doc and update references as
>>>> needed.
>>>>
>>>> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
>>>> ---
>>>> Documentation/sphinx/kernel_feat.py | 4 ++--
>>>> .../features/scripts => tools/doc}/features-refresh.sh | 0
>>>> {scripts => tools/doc}/get_feat.pl | 2 +-
>>>
>>> This one is the next on my list to convert to Python, but I didn't
>>> do any changes on it yet.
>>
>> Just curious, why does it need to be converted from shell to Python?
>> I'm sure you will explain that in the patch description (or cover letter).
>
> The rationale is the same as kernel-doc and get-abi: there is a Sphinx
> extension that executes it. By converting it into Python and splitting
> the code into an exec and a library, we can use the library directly at
> the extension.
>
> Besides that, the code in Python, specially after using modules and
> classes, become IMO clearer, making easier to maintain, specially if
> we avoid functions inside functions, complex class inheritance, lamba
> functions and multiple statements on a single line.
Thank you for that.
--
~Randy
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 07/13] docs: move sphinx-pre-install to tools/doc
2025-08-14 2:14 ` Jonathan Corbet
@ 2025-08-14 6:21 ` Mauro Carvalho Chehab
2025-08-14 13:52 ` Jonathan Corbet
0 siblings, 1 reply; 47+ messages in thread
From: Mauro Carvalho Chehab @ 2025-08-14 6:21 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Akira Yokosawa, Randy Dunlap
Em Wed, 13 Aug 2025 20:14:42 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
>
> > Em Wed, 13 Aug 2025 15:32:06 -0600
> > Jonathan Corbet <corbet@lwn.net> escreveu:
> >
> >> Put this tool with the other documentation-related scripts.
> >
> > This one will be painful, as it will cause conflicts with my series
> > that clean up the docs Makefile.
>
> Just in general ... I'm more than happy to put this whole series on the
> back burner until we've gotten that other stuff merged ... it's an RFC
> after all, and there's no urgency here.
Ok, thanks! Yeah, this would help avoiding conflicts with the patches
I have piled here.
Btw, as I said I have a /51 patch series focused on parse-headers.pl
and kernel_include.py, which is currently used only by media docs.
For those who don't know, this was added at the very beginning of
Sphinx adoption, and had its own particular way to create *.rst
files from source code with cross references, via an specially crafted
Makefile that runs before Sphinx. This was written as a way to detect
uAPI documentation gaps, producing warnings for unsolved cross references.
Recent Sphinx versions broke it by disabling cross-reference warnings.
This series is big (51 patches) because it needs to fix thousands of
broken cross references on media. I may end splitting it on two series
to make easier for review, one for the script and another for media doc
fixes.
Such series affect this RFC as it is creating a tools/docs and placing
there the parse-headers.py code as:
tools/docs/lib/parse_data_structs.py | 230 +++++++++++++++--------------------
tools/docs/parse-headers.py | 5
Now, if you prefer tools/doc instead and/or place the libs elsewhere,
we have a couple of options:
1. rebase my series to do the changes. I suspect that there won't
be much conflicts, but this may delay a little bit sending you
what I have;
2. add a patch at the end moving stuff elsewhere;
3. on your series, move them elsewhere.
What do you prefer?
Thanks,
Mauro
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 10/13] docs: move kernel-doc to tools/doc
2025-08-13 21:32 ` [PATCH 10/13] docs: move kernel-doc " Jonathan Corbet
2025-08-13 23:33 ` Mauro Carvalho Chehab
2025-08-13 23:48 ` Mauro Carvalho Chehab
@ 2025-08-14 12:13 ` kernel test robot
2 siblings, 0 replies; 47+ messages in thread
From: kernel test robot @ 2025-08-14 12:13 UTC (permalink / raw)
To: Jonathan Corbet, linux-doc
Cc: oe-kbuild-all, linux-kernel, Mauro Carvalho Chehab, linux-media,
Akira Yokosawa, Randy Dunlap, Jonathan Corbet
Hi Jonathan,
kernel test robot noticed the following build errors:
[auto build test ERROR on lwn/docs-next]
[also build test ERROR on next-20250814]
[cannot apply to drm-i915/for-linux-next drm-i915/for-linux-next-fixes linus/master v6.17-rc1]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]
url: https://github.com/intel-lab-lkp/linux/commits/Jonathan-Corbet/docs-Move-the-features-tools-to-tools-doc/20250814-053915
base: git://git.lwn.net/linux.git docs-next
patch link: https://lore.kernel.org/r/20250813213218.198582-11-corbet%40lwn.net
patch subject: [PATCH 10/13] docs: move kernel-doc to tools/doc
config: i386-randconfig-011-20250814 (https://download.01.org/0day-ci/archive/20250814/202508141909.XegB3Vla-lkp@intel.com/config)
compiler: gcc-12 (Debian 12.2.0-14+deb12u1) 12.2.0
reproduce (this is a W=1 build): (https://download.01.org/0day-ci/archive/20250814/202508141909.XegB3Vla-lkp@intel.com/reproduce)
If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/oe-kbuild-all/202508141909.XegB3Vla-lkp@intel.com/
All errors (new ones prefixed by >>):
>> /bin/sh: 1: tools/doc/kernel-doc.py: not found
make[3]: *** [scripts/Makefile.build:287: scripts/mod/empty.o] Error 127 shuffle=1730989061
make[3]: *** Deleting file 'scripts/mod/empty.o'
make[3]: Target 'scripts/mod/' not remade because of errors.
make[2]: *** [Makefile:1281: prepare0] Error 2 shuffle=1730989061
make[2]: Target 'prepare' not remade because of errors.
make[1]: *** [Makefile:248: __sub-make] Error 2 shuffle=1730989061
make[1]: Target 'prepare' not remade because of errors.
make: *** [Makefile:248: __sub-make] Error 2 shuffle=1730989061
make: Target 'prepare' not remade because of errors.
--
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 07/13] docs: move sphinx-pre-install to tools/doc
2025-08-14 6:21 ` Mauro Carvalho Chehab
@ 2025-08-14 13:52 ` Jonathan Corbet
2025-08-15 5:18 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 47+ messages in thread
From: Jonathan Corbet @ 2025-08-14 13:52 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: linux-doc, linux-kernel, Akira Yokosawa, Randy Dunlap
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> This series is big (51 patches) because it needs to fix thousands of
> broken cross references on media. I may end splitting it on two series
> to make easier for review, one for the script and another for media doc
> fixes.
That might help, yes.
> Such series affect this RFC as it is creating a tools/docs and placing
> there the parse-headers.py code as:
>
> tools/docs/lib/parse_data_structs.py | 230 +++++++++++++++--------------------
> tools/docs/parse-headers.py | 5
>
> Now, if you prefer tools/doc instead and/or place the libs elsewhere,
> we have a couple of options:
>
> 1. rebase my series to do the changes. I suspect that there won't
> be much conflicts, but this may delay a little bit sending you
> what I have;
>
> 2. add a patch at the end moving stuff elsewhere;
>
> 3. on your series, move them elsewhere.
>
> What do you prefer?
Between "tools/doc" and "tools/docs" I don't really have overly strong
feelings; if you work has the latter we can just stick with that. If
you propose "tools/Documentation", though, expect resistance :)
As I said, my series was an RFC to see what it would look like; it did't
take all that long the first time around, and will be even quicker to
redo on top of a new base, whatever that turns out to be.
Thanks,
jon
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH RFC 00/13] Collect documention-related tools under tools/doc
2025-08-13 21:31 [PATCH RFC 00/13] Collect documention-related tools under tools/doc Jonathan Corbet
` (14 preceding siblings ...)
2025-08-13 23:29 ` Mauro Carvalho Chehab
@ 2025-08-14 14:59 ` Jani Nikula
2025-08-15 2:53 ` Randy Dunlap
15 siblings, 1 reply; 47+ messages in thread
From: Jani Nikula @ 2025-08-14 14:59 UTC (permalink / raw)
To: Jonathan Corbet, linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa, Randy Dunlap,
Jonathan Corbet
On Wed, 13 Aug 2025, Jonathan Corbet <corbet@lwn.net> wrote:
> Our documentation-related tools are spread out over various directories;
> several are buried in the scripts/ dumping ground. That makes them harder
> to discover and harder to maintain.
>
> Recently, the idea of creating a dedicated directory for documentation tools
> came up; I decided to see what it would look like. This series creates a
> new directory, tools/doc, and moves various utilities there, hopefully
> fixing up all of the relevant references in the process.
>
> At the end, rather than move the old, Perl kernel-doc, I simply removed it.
A wholehearted
Acked-by: Jani Nikula <jani.nikula@intel.com>
on all of it.
> The big elephant lurking in this small room is the home for Python modules;
> I left them under scripts/lib, but that is an even less appropriate place
> than it was before. I would propose either tools/python or lib/python;
> thoughts on that matter welcome.
lib/ contains code that's built into the kernel, I think lib/python
would be out of place.
IMO tools/python (or tools/lib/python, no strong opinion) is more
appropriate.
BR,
Jani.
--
Jani Nikula, Intel
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 13/13] docs: remove kernel-doc.pl
2025-08-13 21:32 ` [PATCH 13/13] docs: remove kernel-doc.pl Jonathan Corbet
2025-08-13 23:33 ` Mauro Carvalho Chehab
@ 2025-08-15 2:43 ` Randy Dunlap
2025-08-15 4:45 ` Mauro Carvalho Chehab
1 sibling, 1 reply; 47+ messages in thread
From: Randy Dunlap @ 2025-08-15 2:43 UTC (permalink / raw)
To: Jonathan Corbet, linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa
On 8/13/25 2:32 PM, Jonathan Corbet wrote:
> We've been using the Python version and nobody has missed this one. All
> credit goes to Mauro Carvalho Chehab for creating the replacement.
Thanks, Mauro. I certainly won't miss kernel-doc.pl.
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
> scripts/kernel-doc.pl | 2439 -----------------------------------------
> 1 file changed, 2439 deletions(-)
> delete mode 100755 scripts/kernel-doc.pl
--
~Randy
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH RFC 00/13] Collect documention-related tools under tools/doc
2025-08-14 14:59 ` Jani Nikula
@ 2025-08-15 2:53 ` Randy Dunlap
2025-08-15 8:29 ` Jani Nikula
0 siblings, 1 reply; 47+ messages in thread
From: Randy Dunlap @ 2025-08-15 2:53 UTC (permalink / raw)
To: Jani Nikula, Jonathan Corbet, linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa
On 8/14/25 7:59 AM, Jani Nikula wrote:
> On Wed, 13 Aug 2025, Jonathan Corbet <corbet@lwn.net> wrote:
>> Our documentation-related tools are spread out over various directories;
>> several are buried in the scripts/ dumping ground. That makes them harder
>> to discover and harder to maintain.
>>
>> Recently, the idea of creating a dedicated directory for documentation tools
>> came up; I decided to see what it would look like. This series creates a
>> new directory, tools/doc, and moves various utilities there, hopefully
>> fixing up all of the relevant references in the process.
>>
>> At the end, rather than move the old, Perl kernel-doc, I simply removed it.
>
> A wholehearted
>
> Acked-by: Jani Nikula <jani.nikula@intel.com>
>
> on all of it.
and
Acked-by: Randy Dunlap <rdunlap@infradead.org>
for the series.
along with using either of tools/doc/ or tools/docs/.
>> The big elephant lurking in this small room is the home for Python modules;
>> I left them under scripts/lib, but that is an even less appropriate place
>> than it was before. I would propose either tools/python or lib/python;
>> thoughts on that matter welcome.
>
> lib/ contains code that's built into the kernel, I think lib/python
> would be out of place.
Would tools/docs/lib be OK?
I wouldn't tie it up to a specific language,
but I don't have a strong opinion either way.
> IMO tools/python (or tools/lib/python, no strong opinion) is more
> appropriate.
--
~Randy
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 13/13] docs: remove kernel-doc.pl
2025-08-15 2:43 ` Randy Dunlap
@ 2025-08-15 4:45 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 47+ messages in thread
From: Mauro Carvalho Chehab @ 2025-08-15 4:45 UTC (permalink / raw)
To: Randy Dunlap; +Cc: Jonathan Corbet, linux-doc, linux-kernel, Akira Yokosawa
Em Thu, 14 Aug 2025 19:43:38 -0700
Randy Dunlap <rdunlap@infradead.org> escreveu:
> On 8/13/25 2:32 PM, Jonathan Corbet wrote:
> > We've been using the Python version and nobody has missed this one. All
> > credit goes to Mauro Carvalho Chehab for creating the replacement.
>
> Thanks, Mauro. I certainly won't miss kernel-doc.pl.
Anytime. I'm very glad to see that the Python version have been work
nicely, and having you, Jon and others looking on its code. My feeling
is that it will be easier to maintain.
>
> > Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> > ---
> > scripts/kernel-doc.pl | 2439 -----------------------------------------
> > 1 file changed, 2439 deletions(-)
> > delete mode 100755 scripts/kernel-doc.pl
>
Thanks,
Mauro
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 07/13] docs: move sphinx-pre-install to tools/doc
2025-08-14 13:52 ` Jonathan Corbet
@ 2025-08-15 5:18 ` Mauro Carvalho Chehab
2025-08-15 13:18 ` Jonathan Corbet
0 siblings, 1 reply; 47+ messages in thread
From: Mauro Carvalho Chehab @ 2025-08-15 5:18 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Akira Yokosawa, Randy Dunlap
Em Thu, 14 Aug 2025 07:52:22 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
>
> > This series is big (51 patches) because it needs to fix thousands of
> > broken cross references on media. I may end splitting it on two series
> > to make easier for review, one for the script and another for media doc
> > fixes.
>
> That might help, yes.
>
> > Such series affect this RFC as it is creating a tools/docs and placing
> > there the parse-headers.py code as:
> >
> > tools/docs/lib/parse_data_structs.py | 230 +++++++++++++++--------------------
> > tools/docs/parse-headers.py | 5
> >
> > Now, if you prefer tools/doc instead and/or place the libs elsewhere,
> > we have a couple of options:
> >
> > 1. rebase my series to do the changes. I suspect that there won't
> > be much conflicts, but this may delay a little bit sending you
> > what I have;
> >
> > 2. add a patch at the end moving stuff elsewhere;
> >
> > 3. on your series, move them elsewhere.
> >
> > What do you prefer?
>
> Between "tools/doc" and "tools/docs" I don't really have overly strong
> feelings; if you work has the latter we can just stick with that. If
> you propose "tools/Documentation", though, expect resistance :)
<joke>
Heh, I'm tempted to propose:
/Documentation -> /docs
or
/Documentation -> /Docs
</joke>
Ok, so let's keep tools/docs then. We need to decide about python
lib. On my series, I'm placing at tools/docs/lib, but I guess we
can change it later.
From my side, I would prefer to have a single directory for tools,
as we may place there things that aren't specific to docs.
For instance, I have my own class that I use for command execution,
using asyncio. The rationale is that it allows output messages in
real time without needing to wait for the entire process to end(*).
(*) I recently discovered a way to do that without needing asyncio,
which makes the code a little bit simpler.
Either using asyncio or not, a class for such purpose is something
that multiple tools could use. So, a generic dir like tools/lib,
lib/python, ... IMO makes sense.
> As I said, my series was an RFC to see what it would look like; it did't
> take all that long the first time around, and will be even quicker to
> redo on top of a new base, whatever that turns out to be.
With regards to the RFC, IMO we still may need to discuss how we'll end
placing libraries under a LIBDIR. IMO, your RFC should also propose
a directory structure. I mean, we could have something like:
LIBDIR # either tools/docs/lib, tools/lib, lib/python or whatever
|
+---> common
\---> docs
|
+---> kdoc
\---> abi
We could instead do:
- flatten "common" to LIBDIR; or:
- flatten "docs" to LIBDIR; or:
- flatten both but keeping kdoc, abi, ... directories inside
LIBDIR; or:
- have a completely flatten directory with everything
under LIBDIR.
> Thanks,
>
> jon
Thanks,
Mauro
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH RFC 00/13] Collect documention-related tools under tools/doc
2025-08-15 2:53 ` Randy Dunlap
@ 2025-08-15 8:29 ` Jani Nikula
0 siblings, 0 replies; 47+ messages in thread
From: Jani Nikula @ 2025-08-15 8:29 UTC (permalink / raw)
To: Randy Dunlap, Jonathan Corbet, linux-doc
Cc: linux-kernel, Mauro Carvalho Chehab, Akira Yokosawa
On Thu, 14 Aug 2025, Randy Dunlap <rdunlap@infradead.org> wrote:
> Would tools/docs/lib be OK?
> I wouldn't tie it up to a specific language,
> but I don't have a strong opinion either way.
I think the question is, is the directory for libraries used by
documentation tools *or* for python libraries used by tools in general?
I would lean towards the latter, to not create another dilemma when a
library is used by both documentation and other tools.
BR,
Jani.
--
Jani Nikula, Intel
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 07/13] docs: move sphinx-pre-install to tools/doc
2025-08-15 5:18 ` Mauro Carvalho Chehab
@ 2025-08-15 13:18 ` Jonathan Corbet
2025-08-15 15:13 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 47+ messages in thread
From: Jonathan Corbet @ 2025-08-15 13:18 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: linux-doc, linux-kernel, Akira Yokosawa, Randy Dunlap
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
>> Between "tools/doc" and "tools/docs" I don't really have overly strong
>> feelings; if you work has the latter we can just stick with that. If
>> you propose "tools/Documentation", though, expect resistance :)
>
> <joke>
> Heh, I'm tempted to propose:
> /Documentation -> /docs
> or
> /Documentation -> /Docs
> </joke>
I proposed the former at a maintainers summit a few years ago ... the
response was less than fully positive. I guess the fact that docs have
the longest and only capitalized top-level directory name shows their
relative importance :)
> Ok, so let's keep tools/docs then. We need to decide about python
> lib. On my series, I'm placing at tools/docs/lib, but I guess we
> can change it later.
>
> From my side, I would prefer to have a single directory for tools,
> as we may place there things that aren't specific to docs.
>
> For instance, I have my own class that I use for command execution,
> using asyncio. The rationale is that it allows output messages in
> real time without needing to wait for the entire process to end(*).
>
> (*) I recently discovered a way to do that without needing asyncio,
> which makes the code a little bit simpler.
This is just flushing the output buffer? Asyncio seems like a heavy
tool for that; I guess I'm missing something.
> Either using asyncio or not, a class for such purpose is something
> that multiple tools could use. So, a generic dir like tools/lib,
> lib/python, ... IMO makes sense.
I agree with this, anyway. "tools/python" might end up as the winning
suggestion.
>> As I said, my series was an RFC to see what it would look like; it did't
>> take all that long the first time around, and will be even quicker to
>> redo on top of a new base, whatever that turns out to be.
>
> With regards to the RFC, IMO we still may need to discuss how we'll end
> placing libraries under a LIBDIR. IMO, your RFC should also propose
> a directory structure. I mean, we could have something like:
>
> LIBDIR # either tools/docs/lib, tools/lib, lib/python or whatever
> |
> +---> common
> \---> docs
> |
> +---> kdoc
> \---> abi
>
> We could instead do:
> - flatten "common" to LIBDIR; or:
> - flatten "docs" to LIBDIR; or:
> - flatten both but keeping kdoc, abi, ... directories inside
> LIBDIR; or:
> - have a completely flatten directory with everything
> under LIBDIR.
I'm not sure we need the common/docs intermediate directory.
Meanwhile, I had a related, possibly unpopular idea... Start with
.../tools/python/kernel and put a basic __init__.py file there;
everything else would go into that directory or before. The imports
would then read something like:
from kernel import abi_parser
That would make it clear which modules are ours and which come from
elsewhere.
I was planning to toss together another RFC with that scheme, again to
see what it would look like in practice.
Thoughts?
jon
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 07/13] docs: move sphinx-pre-install to tools/doc
2025-08-15 13:18 ` Jonathan Corbet
@ 2025-08-15 15:13 ` Mauro Carvalho Chehab
2025-08-15 19:31 ` Jonathan Corbet
0 siblings, 1 reply; 47+ messages in thread
From: Mauro Carvalho Chehab @ 2025-08-15 15:13 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Akira Yokosawa, Randy Dunlap
Em Fri, 15 Aug 2025 07:18:51 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
>
> >> Between "tools/doc" and "tools/docs" I don't really have overly strong
> >> feelings; if you work has the latter we can just stick with that. If
> >> you propose "tools/Documentation", though, expect resistance :)
> >
> > <joke>
> > Heh, I'm tempted to propose:
> > /Documentation -> /docs
> > or
> > /Documentation -> /Docs
> > </joke>
>
> I proposed the former at a maintainers summit a few years ago ... the
> response was less than fully positive. I guess the fact that docs have
> the longest and only capitalized top-level directory name shows their
> relative importance :)
:-)
> > Ok, so let's keep tools/docs then. We need to decide about python
> > lib. On my series, I'm placing at tools/docs/lib, but I guess we
> > can change it later.
> >
> > From my side, I would prefer to have a single directory for tools,
> > as we may place there things that aren't specific to docs.
> >
> > For instance, I have my own class that I use for command execution,
> > using asyncio. The rationale is that it allows output messages in
> > real time without needing to wait for the entire process to end(*).
> >
> > (*) I recently discovered a way to do that without needing asyncio,
> > which makes the code a little bit simpler.
>
> This is just flushing the output buffer? Asyncio seems like a heavy
> tool for that; I guess I'm missing something.
Yes, flushing output as they arrive while storing results from stdout and
stderr and handling "stdin", eventually dynamically printing stdin when
debug is enabled. The problem sounds simple, and this is really easy to
implement in Perl. However, on Python, this ends to be a very complex
problem that one can only get all the caveats after implementing unit
tests and then discovering, for instance, that, if stdin is bigger than
32KB, Python read logic freezes forever (or until gather() timeout, and
the stdin was incomplete.
To fix it, one needs to implement a different stdin function that can't
wait anymore for the end of a read operation, but instead needs to pick
buffers in small chunks. Plus, the subprocess execution method requires
some unusual buffering parameters.
> > Either using asyncio or not, a class for such purpose is something
> > that multiple tools could use. So, a generic dir like tools/lib,
> > lib/python, ... IMO makes sense.
>
> I agree with this, anyway. "tools/python" might end up as the winning
> suggestion.
>
> >> As I said, my series was an RFC to see what it would look like; it did't
> >> take all that long the first time around, and will be even quicker to
> >> redo on top of a new base, whatever that turns out to be.
> >
> > With regards to the RFC, IMO we still may need to discuss how we'll end
> > placing libraries under a LIBDIR. IMO, your RFC should also propose
> > a directory structure. I mean, we could have something like:
> >
> > LIBDIR # either tools/docs/lib, tools/lib, lib/python or whatever
> > |
> > +---> common
> > \---> docs
> > |
> > +---> kdoc
> > \---> abi
> >
> > We could instead do:
> > - flatten "common" to LIBDIR; or:
> > - flatten "docs" to LIBDIR; or:
> > - flatten both but keeping kdoc, abi, ... directories inside
> > LIBDIR; or:
> > - have a completely flatten directory with everything
> > under LIBDIR.
>
> I'm not sure we need the common/docs intermediate directory.
>
> Meanwhile, I had a related, possibly unpopular idea... Start with
> .../tools/python/kernel and put a basic __init__.py file there;
> everything else would go into that directory or before. The imports
> would then read something like:
>
> from kernel import abi_parser
Not against something similar to it, but IMO "kernel" is a bad
name as it sounds something that runs in kernel stace or for Kernel
build. It could be, instead:
from lib import abi_parser
Yet, I guess it may still need to add something at PATH, depending from
where current working dir the script was called (but tests required).
For instance Documentation/sphinx would need to pick lib from
"../../tools/python". So, I guess Sphinx extensions need first to
do:
sys.path.insert(0, "../../tools/python")
and then:
from lib import abi_parser # or:
from lib.abi import abi_parser # or:
import .abi_parser
Btw, nothing prevents moving extensions from Documentation/sphinx
into tools/sphinx_extensions. We just need to add the path insert
at conf.py.
> That would make it clear which modules are ours and which come from
> elsewhere.
>
> I was planning to toss together another RFC with that scheme, again to
> see what it would look like in practice.
> Thoughts?
Fine from my side.
Regards,
Mauro
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 07/13] docs: move sphinx-pre-install to tools/doc
2025-08-15 15:13 ` Mauro Carvalho Chehab
@ 2025-08-15 19:31 ` Jonathan Corbet
2025-08-16 9:34 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 47+ messages in thread
From: Jonathan Corbet @ 2025-08-15 19:31 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: linux-doc, linux-kernel, Akira Yokosawa, Randy Dunlap
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
>> I'm not sure we need the common/docs intermediate directory.
>>
>> Meanwhile, I had a related, possibly unpopular idea... Start with
>> .../tools/python/kernel and put a basic __init__.py file there;
>> everything else would go into that directory or before. The imports
>> would then read something like:
>>
>> from kernel import abi_parser
>
> Not against something similar to it, but IMO "kernel" is a bad
> name as it sounds something that runs in kernel stace or for Kernel
> build. It could be, instead:
>
> from lib import abi_parser
Part of my purpose was to make it clear that the import was coming from
our own library - to distinguish it from all of the other imports that
these programs have. "Kernel" seems good to me, but we could call it
"kernel_lib" or some such if we really want. "lib" seems too generic.
> Yet, I guess it may still need to add something at PATH, depending from
> where current working dir the script was called (but tests required).
That seems hard to avoid, yes.
Of course, we could require that all kernel tools run in a special
virtualenv :)
> Btw, nothing prevents moving extensions from Documentation/sphinx
> into tools/sphinx_extensions. We just need to add the path insert
> at conf.py.
I feel less of a need to do that; it seems that the Sphinx-specific
stuff can stay where it is. Though I guess I wouldn't scream too loud
if people really wanted to do that move.
Thanks,
jon
^ permalink raw reply [flat|nested] 47+ messages in thread
* Re: [PATCH 07/13] docs: move sphinx-pre-install to tools/doc
2025-08-15 19:31 ` Jonathan Corbet
@ 2025-08-16 9:34 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 47+ messages in thread
From: Mauro Carvalho Chehab @ 2025-08-16 9:34 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel, Akira Yokosawa, Randy Dunlap
Em Fri, 15 Aug 2025 13:31:45 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
>
> >> I'm not sure we need the common/docs intermediate directory.
> >>
> >> Meanwhile, I had a related, possibly unpopular idea... Start with
> >> .../tools/python/kernel and put a basic __init__.py file there;
> >> everything else would go into that directory or before. The imports
> >> would then read something like:
> >>
> >> from kernel import abi_parser
> >
> > Not against something similar to it, but IMO "kernel" is a bad
> > name as it sounds something that runs in kernel stace or for Kernel
> > build. It could be, instead:
> >
> > from lib import abi_parser
>
> Part of my purpose was to make it clear that the import was coming from
> our own library - to distinguish it from all of the other imports that
> these programs have. "Kernel" seems good to me, but we could call it
> "kernel_lib" or some such if we really want. "lib" seems too generic.
Ok. let's stick with "Kernel" then.
> > Yet, I guess it may still need to add something at PATH, depending from
> > where current working dir the script was called (but tests required).
>
> That seems hard to avoid, yes.
>
> Of course, we could require that all kernel tools run in a special
> virtualenv :)
No need. Yet, if you look at sphinx-build-wrapper, it has a "-V"
command line. If used, it will either pick a venv name or seek for
sphinx_latest and run from there. I wrote it mainly to help me
on my main devel machine, where I opted to have several different
venvs instead of installing via OS.
I was tempted of making the tool autodetect venv, if sphinx-build
is not found. I opted to not do it for now, but keeping it in mind
for a possible future change. There is also a code that detect if
Python is too old, running a newer version of it if found at the
system if required by the tool to run.
Maybe we can place both logic into a library and let most tools
use it, adjusting the main function call to something like:
MIN_PYTHON_VERSION = (3, x, y)
def main(...):
...
if __name__ == "__main__":
run_on_version(MIN_PYTHON_VERSION, run, use_venv_if_available=True)
> > Btw, nothing prevents moving extensions from Documentation/sphinx
> > into tools/sphinx_extensions. We just need to add the path insert
> > at conf.py.
>
> I feel less of a need to do that; it seems that the Sphinx-specific
> stuff can stay where it is. Though I guess I wouldn't scream too loud
> if people really wanted to do that move.
Ok. As on extensions we always have srctree set (sphinx-build-wrapper
warrants that), the PATH will always be relative to the kernel
directory, e.g.:
srctree = os.path.abspath(os.environ["srctree"])
sys.path.insert(0, os.path.join(srctree, "tools/python"))
from Kernel import abi_parser
The only advantage of moving them to tools/python would be to remove
the need of "srctree" env, using instead os.path.dirname(__file__),
e.g.:
sys.path.insert(0, os.path.dirname(os.path.realpath(__file__)))
from Kernel import abi_parser
but still at lease some extensions still need srctree anyway. So,
not really necessary.
So, let's not touch it then.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 47+ messages in thread
end of thread, other threads:[~2025-08-16 9:34 UTC | newest]
Thread overview: 47+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2025-08-13 21:31 [PATCH RFC 00/13] Collect documention-related tools under tools/doc Jonathan Corbet
2025-08-13 21:32 ` [PATCH 01/13] docs: Move the "features" tools to tools/doc Jonathan Corbet
2025-08-13 23:38 ` Mauro Carvalho Chehab
2025-08-13 23:42 ` Randy Dunlap
2025-08-14 5:56 ` Mauro Carvalho Chehab
2025-08-14 5:57 ` Randy Dunlap
2025-08-13 21:32 ` [PATCH 02/13] docs: move checktransupdate.py " Jonathan Corbet
2025-08-13 23:51 ` Mauro Carvalho Chehab
2025-08-13 21:32 ` [PATCH 03/13] docs: move scripts/check-variable-fonts.sh " Jonathan Corbet
2025-08-13 23:46 ` Mauro Carvalho Chehab
2025-08-13 21:32 ` [PATCH 04/13] docs: move scripts/documentation-file-ref-check " Jonathan Corbet
2025-08-13 23:47 ` Mauro Carvalho Chehab
2025-08-13 21:32 ` [PATCH 05/13] docs: move parallel-wrapper.sh to tools/doc/ Jonathan Corbet
2025-08-13 23:31 ` Mauro Carvalho Chehab
2025-08-13 21:32 ` [PATCH 06/13] docs: move get_abi.py to tools/doc Jonathan Corbet
2025-08-13 23:43 ` Mauro Carvalho Chehab
2025-08-13 21:32 ` [PATCH 07/13] docs: move sphinx-pre-install " Jonathan Corbet
2025-08-13 23:36 ` Mauro Carvalho Chehab
2025-08-14 2:14 ` Jonathan Corbet
2025-08-14 6:21 ` Mauro Carvalho Chehab
2025-08-14 13:52 ` Jonathan Corbet
2025-08-15 5:18 ` Mauro Carvalho Chehab
2025-08-15 13:18 ` Jonathan Corbet
2025-08-15 15:13 ` Mauro Carvalho Chehab
2025-08-15 19:31 ` Jonathan Corbet
2025-08-16 9:34 ` Mauro Carvalho Chehab
2025-08-13 21:32 ` [PATCH 08/13] docs: move test_doc_build.py " Jonathan Corbet
2025-08-13 23:36 ` Mauro Carvalho Chehab
2025-08-13 21:32 ` [PATCH 09/13] docs: move parse-headers.pl " Jonathan Corbet
2025-08-13 23:32 ` Mauro Carvalho Chehab
2025-08-13 21:32 ` [PATCH 10/13] docs: move kernel-doc " Jonathan Corbet
2025-08-13 23:33 ` Mauro Carvalho Chehab
2025-08-13 23:48 ` Mauro Carvalho Chehab
2025-08-14 12:13 ` kernel test robot
2025-08-13 21:32 ` [PATCH 11/13] docs: move split-man.pl " Jonathan Corbet
2025-08-13 23:50 ` Mauro Carvalho Chehab
2025-08-13 21:32 ` [PATCH 12/13] docs: move find-unused-docs.sh " Jonathan Corbet
2025-08-13 23:50 ` Mauro Carvalho Chehab
2025-08-13 21:32 ` [PATCH 13/13] docs: remove kernel-doc.pl Jonathan Corbet
2025-08-13 23:33 ` Mauro Carvalho Chehab
2025-08-15 2:43 ` Randy Dunlap
2025-08-15 4:45 ` Mauro Carvalho Chehab
2025-08-13 21:38 ` [PATCH RFC 00/13] Collect documention-related tools under tools/doc Jonathan Corbet
2025-08-13 23:29 ` Mauro Carvalho Chehab
2025-08-14 14:59 ` Jani Nikula
2025-08-15 2:53 ` Randy Dunlap
2025-08-15 8:29 ` Jani Nikula
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).