linux-kernel - [PATCH] Makefile: Get back to kernel-doc.pl as KERNELDOC default

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-ID: <d9d0ff79-a243-456e-a7ed-eaca69d2eca7@gmail.com>
Date: Tue, 20 May 2025 09:08:51 +0900
From: Akira Yokosawa <akiyks@...il.com>
To: Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org
Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
 Masahiro Yamada <masahiroy@...nel.org>, Nathan Chancellor
 <nathan@...nel.org>, Nicolas Schier <nicolas.schier@...ux.dev>,
 Andy Shevchenko <andriy.shevchenko@...ux.intel.com>,
 Stephen Rothwell <sfr@...b.auug.org.au>, Randy Dunlap
 <rdunlap@...radead.org>, linux-kbuild@...r.kernel.org,
 linux-kernel@...r.kernel.org, Akira Yokosawa <akiyks@...il.com>
Subject: [PATCH] Makefile: Get back to kernel-doc.pl as KERNELDOC default

Recent conversion of kernel-doc into python has resulted in a couple of
glitches in "make htmldocs" [1, 2, 3].

This is because the python version has not gone through extensive tests
such as fault-injection of erroneous kernel-doc comments and/or
kernel-doc:: directives.

Python kernel-doc as it is does not meet the usual expectation of
backward-compatibility with its perl predecessor.

Get back to the perl version as KENRELDOC default for now.

Reported-by: Stephen Rothwell <sfr@...b.auug.org.au>
Link: https://lore.kernel.org/20250508182504.418552ef@canb.auug.org.au/ [1]
Link: https://lore.kernel.org/20250516193436.09bdf8cc@canb.auug.org.au/ [2]
Link: https://lore.kernel.org/20250516200350.63be46cd@canb.auug.org.au/ [3]
Signed-off-by: Akira Yokosawa <akiyks@...il.com>
Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
---
This one-liner is just a workaround, hence no Fixes: or Closes: tags.

Jon, it looks like we are running out of time for the upcoming merge window.
Let's take another development cycle for stabilizing kernel-doc in python.

Additional notes on glitches reported so far.

* Depending on the version of Sphinx, the crashing message can be useless
  for finding out what is going on [1, 2].
  With up-to-date Sphinx, the message even suggests a *bug* somewhere in
  Sphinx and includes a traceback to be reported as an issue at upstream
  Sphinx [4].

* The python version of kernel-doc fails to produce warnings on innocuous
  issues under Sphinx runs [3], which have been available with the perl
  version.

[4]: https://lore.kernel.org/879b49f5-7350-48e8-a84e-2c580a5b0ca8@gmail.com/
---
 Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index 2a05988740a9..c2c9f5af4986 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)/scripts/kernel-doc.pl
 export KERNELDOC

 KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \

base-commit: a556bd882b9482f1b7ea00fcf07f9bc169f404c8
-- 
2.43.0