linux-kernel - Re: [PATCH v3 0/8] Collect documentation-related tools under /tools/docs

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-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <874irkp97o.fsf@trenco.lwn.net>
Date: Mon, 27 Oct 2025 11:04:27 -0600
From: Jonathan Corbet <corbet@....net>
To: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>, Akira Yokosawa
 <akiyks@...il.com>
Cc: linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org, Randy Dunlap
 <rdunlap@...radead.org>, Jani
 Nikula <jani.nikula@...ux.intel.com>
Subject: Re: [PATCH v3 0/8] Collect documentation-related tools under
 /tools/docs

Mauro Carvalho Chehab <mchehab+huawei@...nel.org> writes:

> Patch is incomplete, as it doesn't drop the logic which forks
> kernel-doc script run, but see below.

So I clearly hadn't fully understood how this works.  Before I went and
broke things, the logic seemed to be:

  If the kerneldoc_bin environment variable is "kernel-doc.py"
  	don't actually run kernel-doc.py, build it internally instead
  else
  	run whatever program the variable points to

  ...
  set kerneldoc_bin to "kernel-doc.py" by default

This seems ... a bit obscure.  Given that:

> 3. change the core of the logic to be something like:
> 
> 	# kerneldoc_bin = env.config.kerneldoc_bin
> 	kerneldoc_bin = os.environ.get("KERNELDOC")
> 
> 	if not kerneldoc_bin:
> 	   out_style = RestFormat()
> 	   kfiles = KernelFiles(out_style=out_style, logger=logger)
> 	else:
> 	    print(f"Generating C documentation by running {kerneldoc_bin} binary")
> 
>    this would still allow using KERNELDOC to point to a binary
>    that will handle C files executed as a separate process.

This seems like an obvious improvement, and one that, perhaps, should go
in ahead of my current series in the perhaps vain hope that we're
finally getting to the end of the list of things I can find to break...

I can send a patch around in the next couple of days if you don't beat
me to it.

jon