linux/scripts/kernel-doc, branch v6.18

scripts/kernel-doc: switch to use kernel-doc.py

2025-04-09T18:10:34Z

Now that all features are in place, change the kernel-doc alias to point to kernel-doc.py. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/d84a2ad282821928a60b8dcbec305ef7e7bd58e6.1744106242.git.mchehab+huawei@kernel.org

scripts/kernel-doc: add a symlink to the Perl version of kernel-doc

2025-04-09T18:10:32Z

Preserve kernel-doc name, associating with the curent version in Perl. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/a5d69e436287433ad8be066c648a77ffe493c21c.1744106241.git.mchehab+huawei@kernel.org

scripts/kernel-doc: rename it to scripts/kernel-doc.pl

2025-04-09T18:10:32Z

In preparation for deprecating scripts/kernel-doc in favor of a new version written in Perl, rename it to scripts/kernel-doc.pl. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/a8a86136bcf102495f09c24a65817f1600fae0e8.1744106241.git.mchehab+huawei@kernel.org

scripts/kernel-doc: drop dead code for Wcontents_before_sections

2025-03-04T16:47:42Z

There is a warning about contents before sections, which doesn't work, since in_doc_sect variable is always true at the point it is checked. Drop the dead code. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/174a15607fd057c736dc9123c53d0835ce20e68b.1740387599.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet

scripts/kernel-doc: don't add not needed new lines

2025-03-04T16:47:40Z

This helps comparing kernel-doc output with the new .py version of it. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/6b036ef7d746f26d7d0044626b04d1f0880a2188.1740387599.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet

scripts/kernel-doc: drop Sphinx version check

2025-02-13T18:33:33Z

As the current minimal supported Sphinx version is 3.4.3, drop support for older versions. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Kees Cook Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/0d002e7550476a68547ee53ad06cfd8fdcaf7c3a.1739254187.git.mchehab+huawei@kernel.org

scripts/kernel-doc: remove an obscure logic from kernel-doc

2025-02-13T16:44:24Z

Kernel-doc has an obscure logic that uses an external file to map files via a .tmp_filelist.txt file stored at the current directory. The rationale for such code predates git time, as it was added on Kernel v2.4.5.5, with the following description: # 26/05/2001 - Support for separate source and object trees. # Return error code. # Keith Owens from commit 396a6123577d ("v2.4.5.4 -> v2.4.5.5") at the historic tree: https://git.kernel.org/pub/scm/linux/kernel/git/history/history.git/ Support for separate source and object trees is now done on a different way via make O=. There's no logic to create such file, so it sounds to me that this is just dead code. So, drop it. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/fd3b28dec36ba1668325d6770d4c4754414337fc.1739340170.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet

scripts/kernel-doc: fix identifier parsing regex

2024-12-30T18:15:10Z

John wrote: > kernel-doc gets confused by code like the following: > > /** > * define HOMA_MIN_DEFAULT_PORT - The 16-bit port space is divided into > * two nonoverlapping regions. Ports 1-32767 are reserved exclusively > * for well-defined server ports. The remaining ports are used for client > * ports; these are allocated automatically by Homa. Port 0 is reserved. > */ > #define HOMA_MIN_DEFAULT_PORT 0x8000 > > It seems to use the last "-" on the line (the one in "16-bit") rather > than the first one, so it produces the following false error message: > > homa.h:50: warning: expecting prototype for HOMA_MIN_DEFAULT_PORT - > The 16(). Prototype was for HOMA_MIN_DEFAULT_PORT() instead > > There are similar problems if there is a ":" later on the line. The problem is the regex for the identifier, which is a greedy /.*/ that matches everything up to the last - or : (i.e. $decl_end). Fix it by tightening up this regex and not matching those characters as part of the identifier. Link: https://lore.kernel.org/all/CAGXJAmzfRzE=A94NT5ETtj3bZc-=2oLg-9E5Kjh4o_-iuw1q8g@mail.gmail.com/ Reported-by: John Ousterhout Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Vegard Nossum Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20241221222214.1969823-1-vegard.nossum@oracle.com

scripts/kernel-doc: Get -export option working again

2024-12-11T16:15:26Z

Since commit cdd30ebb1b9f ("module: Convert symbol namespace to string literal"), exported symbols marked by EXPORT_SYMBOL_NS(_GPL) are ignored by "kernel-doc -export" in fresh build of "make htmldocs". This is because regex in the perl script for those markers fails to match the new signatures: - EXPORT_SYMBOL_NS(symbol, "ns"); - EXPORT_SYMBOL_NS_GPL(symbol, "ns"); Update the regex so that it matches quoted string. Note: Escape sequence of \w is good for C identifiers, but can be too strict for quoted strings. Instead, use \S, which matches any non-whitespace character, for compatibility with possible extension of namespace convention in the future [1]. Fixes: cdd30ebb1b9f ("module: Convert symbol namespace to string literal") Link: https://lore.kernel.org/CAK7LNATMufXP0EA6QUE9hBkZMa6vJO6ZiaYuak2AhOrd2nSVKQ@mail.gmail.com/ [1] Signed-off-by: Akira Yokosawa Cc: Masahiro Yamada Tested-by: Randy Dunlap Acked-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/e5c43f36-45cd-49f4-b7b8-ff342df3c7a4@gmail.com

kernel-doc: allow object-like macros in ReST output

2024-10-17T15:33:29Z

output_function_rst() does not handle object-like macros. It presents a trailing "()" while output_function_man() handles these macros correctly. Update output_function_rst() to handle object-like macros. Don't show the "Parameters" heading if there are no parameters. For output_function_man(), don't show the "ARGUMENTS" heading if there are no parameters. I have tested this quite a bit with my ad hoc test files for both ReST and man format outputs. The generated output looks good. Fixes: cbb4d3e6510b ("scripts/kernel-doc: handle object-like macros") Signed-off-by: Randy Dunlap Cc: Horia Geanta Tested-by: Vlastimil Babka Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20241015181107.536894-1-rdunlap@infradead.org