kernel/linux.git/scripts/lib/kdoc, branch master

docs: Move the python libraries to tools/lib/python

2025-11-18T16:22:40+00:00

"scripts/lib" was always a bit of an awkward place for Python modules. We already have tools/lib; create a tools/lib/python, move the libraries there, and update the users accordingly. While at it, move the contents of tools/docs/lib. Rather than make another directory, just put these documentation-oriented modules under "kdoc". Signed-off-by: Jonathan Corbet Message-ID: <20251110220430.726665-2-corbet@lwn.net>

scripts: docs: kdoc_files.py: don't consider symlinks as directories

2025-11-13T16:16:15+00:00

As reported by Randy, currently kdoc_files can go into endless looks when symlinks are used: $ ln -s . Documentation/peci/foo $ ./scripts/kernel-doc Documentation/peci/ ... File "/new_devel/docs/scripts/lib/kdoc/kdoc_files.py", line 52, in _parse_dir if entry.is_dir(): ~~~~~~~~~~~~^^ OSError: [Errno 40] Too many levels of symbolic links: 'Documentation/peci/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo/foo' Prevent that by not considering symlinks as directories. Reported-by: Randy Dunlap Closes: https://lore.kernel.org/linux-doc/80701524-09fd-4d68-8715-331f47c969f2@infradead.org/ Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <73c3450f34e2a4b42ef2ef279d7487c47d22e3bd.1763027622.git.mchehab+huawei@kernel.org>

kernel-doc: Issue warnings that were silently discarded

2025-11-05T18:05:37+00:00

When kernel-doc parses the sections for the documentation some errors may occur. In many cases the warning is simply stored to the current "entry" object. However, in the most of such cases this object gets discarded and there is no way for the output engine to even know about that. To avoid that, check if the "entry" is going to be discarded and if there warnings have been collected, issue them to the current logger as is and then flush the "entry". This fixes the problem that original Perl implementation doesn't have. As of Linux kernel v6.18-rc4 the reproducer can be: $ scripts/kernel-doc -v -none -Wall include/linux/util_macros.h ... Info: include/linux/util_macros.h:138 Scanning doc for function to_user_ptr ... while with the proposed change applied it gives one more line: $ scripts/kernel-doc -v -none -Wall include/linux/util_macros.h ... Info: include/linux/util_macros.h:138 Scanning doc for function to_user_ptr Warning: include/linux/util_macros.h:144 expecting prototype for to_user_ptr(). Prototype was for u64_to_user_ptr() instead ... And with the original Perl script: $ scripts/kernel-doc.pl -v -none -Wall include/linux/util_macros.h ... include/linux/util_macros.h:139: info: Scanning doc for function to_user_ptr include/linux/util_macros.h:149: warning: expecting prototype for to_user_ptr(). Prototype was for u64_to_user_ptr() instead ... Fixes: 9cbc2d3b137b ("scripts/kernel-doc.py: postpone warnings to the output plugin") Signed-off-by: Andy Shevchenko Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20251104215502.1049817-1-andriy.shevchenko@linux.intel.com>

docs: kdoc: fix duplicate section warning message

2025-10-30T21:13:18+00:00

The python version of the kernel-doc parser emits some strange warnings with just a line number in certain cases: $ ./scripts/kernel-doc -Wall -none 'include/linux/virtio_config.h' Warning: 174 Warning: 184 Warning: 190 Warning: include/linux/virtio_config.h:226 No description found for return value of '__virtio_test_bit' Warning: include/linux/virtio_config.h:259 No description found for return value of 'virtio_has_feature' Warning: include/linux/virtio_config.h:283 No description found for return value of 'virtio_has_dma_quirk' Warning: include/linux/virtio_config.h:392 No description found for return value of 'virtqueue_set_affinity' I eventually tracked this down to the lone call of emit_msg() in the KernelEntry class, which looks like: self.emit_msg(self.new_start_line, f"duplicate section name '{name}'\n") This looks like all the other emit_msg calls. Unfortunately, the definition within the KernelEntry class takes only a message parameter and not a line number. The intended message is passed as the warning! Pass the filename to the KernelEntry class, and use this to build the log message in the same way as the KernelDoc class does. To avoid future errors, mark the warning parameter for both emit_msg definitions as a keyword-only argument. This will prevent accidentally passing a string as the warning parameter in the future. Also fix the call in dump_section to avoid an unnecessary additional newline. Fixes: e3b42e94cf10 ("scripts/lib/kdoc/kdoc_parser.py: move kernel entry to a class") Signed-off-by: Jacob Keller Signed-off-by: Jonathan Corbet Message-ID: <20251030-jk-fix-kernel-doc-duplicate-return-warning-v2-1-ec4b5c662881@intel.com>

kernel-doc: output source file name at SEE ALSO

2025-10-01T15:06:06+00:00

for man pages, it is helpful to know from where the man page were generated. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID:

scripts: kdoc_parser.py: warn about Python version only once

2025-09-18T17:19:59+00:00

When running kernel-doc over multiple documents, it emits one error message per file with is not what we want: $ python3.6 scripts/kernel-doc.py . --none ... Warning: ./include/trace/events/swiotlb.h:0 Python 3.7 or later is required for correct results Warning: ./include/trace/events/iommu.h:0 Python 3.7 or later is required for correct results Warning: ./include/trace/events/sock.h:0 Python 3.7 or later is required for correct results ... Change the logic to warn it only once at the library: $ python3.6 scripts/kernel-doc.py . --none Warning: Python 3.7 or later is required for correct results Warning: ./include/cxl/features.h:0 Python 3.7 or later is required for correct results When running from command line, it warns twice, but that sounds ok. Signed-off-by: Mauro Carvalho Chehab Message-ID: <68e54cf8b1201d1f683aad9bc710a99421910356.1758196090.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet

tools: kernel-doc: add a see also section at man pages

2025-09-18T17:19:58+00:00

While cross-references are complex, as related ones can be on different files, we can at least correlate the ones that belong to the same file, adding a SEE ALSO section for them. The result is not bad. See for instance: $ tools/docs/sphinx-build-wrapper --sphinxdirs driver-api/media -- mandocs $ man Documentation/output/driver-api/man/edac_pci_add_device.9 edac_pci_add_device(9) Kernel Hacker's Manual edac_pci_add_device(9) NAME edac_pci_add_device - Insert the 'edac_dev' structure into the edac_pci global list and create sysfs entries associated with edac_pci structure. SYNOPSIS int edac_pci_add_device (struct edac_pci_ctl_info *pci , int edac_idx ); ARGUMENTS pci pointer to the edac_device structure to be added to the list edac_idx A unique numeric identifier to be assigned to the RETURN 0 on Success, or an error code on failure SEE ALSO edac_pci_alloc_ctl_info(9), edac_pci_free_ctl_info(9), edac_pci_alloc_index(9), edac_pci_del_device(9), edac_pci_cre‐ ate_generic_ctl(9), edac_pci_release_generic_ctl(9), edac_pci_create_sysfs(9), edac_pci_remove_sysfs(9) August 2025 edac_pci_add_device edac_pci_add_device(9) Signed-off-by: Mauro Carvalho Chehab Message-ID: Signed-off-by: Jonathan Corbet

docs: kdoc: a few more dump_typedef() tweaks

2025-09-18T16:19:54+00:00

Merge "typedef" into the typedef_type pattern rather than repeating it later, and add some comments. Signed-off-by: Jonathan Corbet

docs: kdoc: remove redundant comment stripping in dump_typedef()

2025-09-18T16:19:54+00:00

By the time we get here, comments have long since been stripped out; there is no need to do it again. Signed-off-by: Jonathan Corbet

docs: kdoc: remove some dead code in dump_typedef()

2025-09-18T16:19:53+00:00

The regex in this block of code makes no sense, and a quick test shows that it never matches anything; simply delete the code. No output changes. Signed-off-by: Jonathan Corbet