Re: [PATCH 00/13] Add kernel-doc modules to Documentation/tools

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

On Thu, Jan 15, 2026 at 02:29:21AM +0100, Mauro Carvalho Chehab wrote:
> Em Wed, 14 Jan 2026 13:46:31 -0700
> Jonathan Corbet <corbet@lwn.net> escreveu:
> 
> > Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> > 
> > >> We could certainly rename it to something different.
> > >> But I really dislike having language extensions on files meant to be
> > >> executed as commands; you shouldn't care what language it's written in
> > >> when you run it.  
> > >
> > > I don't like it either, but Python is really picky on some things.
> > >
> > > The problem here is that this is a Python policy violation. To change
> > > that, one needs to write a PEP and convince Python maintainers to merge
> > > it, together with changes on python "import" directive.  

> > There is a reason that "pip" is called "pip"
> > rather than "pip.py" - the Python folks don't keep those extensions on
> > commands either.
> 
> This would be equivalent of having a tools/docs/kernel-doc like this
> (untested):
> 
> 	#!/usr/bin/env python3
> 	from .kdoc.main import main
> 	if __name__ == '__main__':
> 	    sys.exit(main())
> 
> where the actual argparse code would be inside tools/docs/kdoc/main.py

In time, I'm not suggesting doing that at all.

I don't like the idea of splitting main() into a separate file: at least 
in my head, the absolute minimum size of a script should be to be able 
to handle command line arguments by itself, without including a module 
for it.

> 	class docs.kernel_doc.MsgFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)
> 
> 	    Bases: Formatter
> 
> 	    Helper class to format warnings in a similar way to kernel-doc.pl.
> 
> 	    format(record)
> 
> 	        Format the specified record as text.
> 
> 	        The record’s attribute dictionary is used as the operand to a 
> 		string formatting operation which yields the returned string. 
> 		Before formatting the dictionary, a couple of preparatory
> 		steps are carried out. The message attribute of the record
> 		is computed using LogRecord.getMessage(). If the formatting
> 		string uses the time (as determined by a call to usesTime(),
> 		formatTime() is called to format the event time. If there is 
> 		exception information, it is formatted using formatException()
> 		and appended to the message.

I also think that we should move MsgFormatter to a separate file. What 
this class does is that it bolds arguments when argparse displays help. 
It has nothing to do with kernel-doc itself, and can be reused on all 
other places where we use argparse. So, placing it under 
tools/lib/python, outside kdoc dir, IMO makes sense.

The same applies to some other stuff currently under kdoc, like 
enrich_formatter.py. Once the series moving kernel-doc to tools/docs 
gets merged, IMHO the next step would be to do some cleanup at 
tools/lib/python, moving things that aren't independent on the actual 
parser to be outside kdoc directory.

Thanks,
Mauro