linux-kernel - [PATCH RFC 0/1] Implement kernel-doc in python

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-next>] [day] [month] [year] [list]

Message-ID: <cover.1739355534.git.mchehab+huawei@kernel.org>
Date: Wed, 12 Feb 2025 11:39:00 +0100
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Linux Doc Mailing List <linux-doc@...r.kernel.org>,
	Jonathan Corbet <corbet@....net>
Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
	Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
	linux-kernel@...r.kernel.org,
	"Gustavo A. R. Silva" <mchehab+huawei@...nel.org>,
	linux-hardening@...r.kernel.org
Subject: [PATCH RFC 0/1] Implement kernel-doc in python

Hi Jon,

As promised, this RFC provides a kernel-doc tool rewriten in Python, as
a heads-up.

I tried to stay as close as possible of the original perl implementation, as it
helps to double check if each function was properly translated to Python.
This have been helpful debugging troubles that happened during the
conversion.

Once we get this merged, we can work on simplifying or reimplementing
some things. One particular cleanup is to use collections OrderedDict.
Right now, the script use some lists to ensure the right order of functions
and structure arguments, just like the original script. I opted to preserve
it on this version because it makes easier to compare both scripts.

There are still some pending work before reaching a version that would be 
ready fore submission:

- on this RFC, the output doesn't match yet the same output of  kernel-doc
  for lots of files. Once I finish implementing all features, I'll focus on making
  the output identical (except for whitespaces/blank lines). The main focus 
  has been to port the  script, but some tweaks  and fixes are still needed;

- this version also lacks support for -W<filter> parameters:  it will just
  output all warnings. This is the next item on my TODO list.

- on the final patchset, I intend to split classes on multiple files;

- for the final version, I'll add a patch that converts prints at the output
  classes to return strings instead, just like we did for get_abi.py, as it
  helps Sphins kernel-doc class, but for now let's do the changes
  step-by-step;

- as I'm still comparing the results with kernel-doc, I'm not adding yet a
  patch to remove the old tool;

- I didn't change yet the Sphinx kernel-doc extension.

Btw, perhaps instead of preserving the extension as .py, at the final
series, it is probably better to rename kernel-doc to kernel-doc.pl,
then add this one as kernel-doc, and finally remove kernel-doc.pl.

This way, it would be more or less transparent for people that use to
type kernel-doc at the command line.

On this implementation, I got one idea from Markus previous work of
having a class to encapsulate re.compile(). This allowed to simplify the
port while ensuring that almost all regular expressions are compiled
and cached, hopefully improving its performance.

Comments?

Mauro Carvalho Chehab (1):
  scripts/kernel-doc.py: add a Python parser

 scripts/kernel-doc.py | 2674 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 2674 insertions(+)
 create mode 100755 scripts/kernel-doc.py

-- 
2.48.1