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: <20251107072718.36bbda53@sal.lan>
Date: Fri, 7 Nov 2025 07:27:18 -0300
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Jonathan Corbet <corbet@....net>
Cc: Akira Yokosawa <akiyks@...il.com>, 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

Em Tue, 28 Oct 2025 17:15:26 -0600
Jonathan Corbet <corbet@....net> escreveu:

> Jonathan Corbet <corbet@....net> writes:
> 
> >> 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.  
> 
> So I have that change working just fine ... only one problem.
> 
> For this to work, we have to take out the definition of KERNELDOC in the
> top-level Makefile, otherwise we'll never go the import path.  But there
> are a few other Makefiles, mostly in the DRM area, that need that
> definition.

True, DRM makefiles run kernel-doc to check for warnings within the
DRM subsystem. 

>  So I have the docs build working, but I've broken other
> things, and I think people are getting tired of me breaking things.
> 
> Possible solutions:
> 
> - Add a new FORCE_KDOC environment variable that is used instead of
>   KERNELDOC to set the program to run in the docs build.

Works for me.

> - Keep the current logic that special-cases setting KERNELDOC to
>   scripts/kernel-doc.py and really runs in the imported mode in that
>   case.

Not sure if I got what you meant. Do you mean not running the classes
but always run exec() syscall? This will likely affect build time,
and prevent further speedup optimizations. It will also duplicate
warnings if we drop the output filter logic for warnings.

> 
> - Go into retirement and let it be somebody else's problem
> 
> Anybody have any other great ideas?
> 
> Thanks,
> 
> jon