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

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: <aWi8REEsfMt9AnuA@foz.lan>
Date: Thu, 15 Jan 2026 11:17:44 +0100
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Cc: Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org, 
	linux-kernel@...r.kernel.org, 
	Nícolas F. R. A. Prado <nfraprado@...labora.com>, Randy Dunlap <rdunlap@...radead.org>, 
	Shuah Khan <skhan@...uxfoundation.org>
Subject: Re: [PATCH 00/13] Add kernel-doc modules to Documentation/tools

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@....net> escreveu:
> 
> > Mauro Carvalho Chehab <mchehab+huawei@...nel.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