Re: [PATCH] scripts/kernel-doc: remove an obscure logic from kernel-doc

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Thu, 13 Feb 2025 18:38:47 -0800
Randy Dunlap <rdunlap@infradead.org> escreveu:

> Hi--
> 
> On 2/13/25 6:24 PM, Mauro Carvalho Chehab wrote:
> > Em Thu, 13 Feb 2025 09:35:58 -0700
> > Jonathan Corbet <corbet@lwn.net> escreveu:
> >   
> >> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> >>  
> >>> 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 <kaos@ocs.com.au>
> >>>
> >>> 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=<object>.
> >>>
> >>> There's no logic to create such file, so it sounds to me that this is
> >>> just dead code.
> >>>
> >>> So, drop it.
> >>>
> >>> Fixes: 1da177e4c3f4 ("Linux-2.6.12-rc2")
> >>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> >>> ---
> >>>  scripts/kernel-doc | 19 +------------------
> >>>  1 file changed, 1 insertion(+), 18 deletions(-)    
> >>
> >> Weird ... I went and looked, and can't find anything that ever created
> >> that tmp_filelist.txt file; I wonder if this code ever did anything?  
> > 
> > I wonder the same ;-) Anyway, better to remove this now, as, if people
> > complain, it would be easier to revert than after switching to the
> > Python version.
> >   
> >> Don't put that functionality into the Python version :)  
> > 
> > Yeah, I started implementing it, but it sounded a waste of time, so
> > I dropped it from the RFC versions. It sounded too complex for people
> > to maintain a separate tmp file when make O=dir would do it on a much
> > better and automated way.
> > 
> > -
> > 
> > With regards to the Python transition, since our Makefile allows
> > switching to a different script since ever[1], I'm playing with 
> > the idea of sending a patch series with:
> > 
> > Patch 1: 
> >   - drops Sphinx version check from both kerneldoc 
> >     (-sphinx-version parameter) and the corresponding Sphinx extension;
> >   
> 
> It's currently scripts/kernel-doc. Are you planning to change it to
> scripts/kerneldoc and break other scripts and makefiles?

No, the idea is to keep it as kernel-doc.

I always confuse the names as we have both, depending on where you
look at:
	
	- scripts/kernel-doc
	- Documentation/sphinx/kerneldoc.py

The Python version was written to support all command-line parameters
as the original one - although I introduced both a single line and a
two dash alternative.

It also expects the file name(s) to be after the parameters, just like
kernel-doc.

I just changed the logger formatter to be similar to what we have
on kernel-doc:

	Warning: <msg>

So, I expect that such change will cause minimal impact on existing
scripts.

Thanks,
Mauro