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 for Android: free password hash cracker in your pocket

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <87v7h3udlk.fsf@trenco.lwn.net>
Date: Wed, 14 Jan 2026 13:46:31 -0700
From: Jonathan Corbet <corbet@....net>
To: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Cc: 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

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.

...or just ignore it.  There is a reason that "pip" is called "pip"
rather than "pip.py" - the Python folks don't keep those extensions on
commands either.

> Alternatively, assuming that some magic words would be enough to
> convince importlib to load a name without ".py" and with "-", it could be
> easier to convince Sphinx autodoc maintainers to take a patch, as they're 
> probably using importlib somewhere to dynamically import a file based 
> at the string inside "automodule" directive. On a quick grep,
> this seems to be the case, and such logic is inside:
>
> 	sphinx/ext/autodoc/importer.py

No doubt we could do that.  But is it really worth the trouble?  There
is not much in kernel-doc that needs documenting, especially since you
did the work to move the actual functionality into separate modules. 

> So, even if we don't actually add kernel-doc docstrings and
> functions via autodoc, I think it is still worth having a
> name convention that would allow that.

Instead, I think you're trying to take a functionality meant to describe
APIs and use it to document command-line stuff.  I'm happy to live by
the import rules for stuff that is actually imported; I think it makes
less sense to let them drive the naming of files that are outside of
their intended scope.

jon