linux-kernel - Re: [PATCH 03/12] docs: kdoc: backslashectomy in kdoc

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: <87h5yrruki.fsf@trenco.lwn.net>
Date: Fri, 01 Aug 2025 08:21:49 -0600
From: Jonathan Corbet <corbet@....net>
To: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Cc: linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org, Akira Yokosawa
 <akiyks@...il.com>
Subject: Re: [PATCH 03/12] docs: kdoc: backslashectomy in kdoc_parser

Mauro Carvalho Chehab <mchehab+huawei@...nel.org> writes:

> Em Thu, 31 Jul 2025 18:13:17 -0600
> Jonathan Corbet <corbet@....net> escreveu:
>
>> A lot of the regular expressions in this file have extraneous backslashes
>
> This one is a bit scary... It could actually cause issues somewhere.

What kind of issues?

> Also, IMHO, some expressions look worse on my eyes ;-)

Here I think we're going to disagree.  The extra backslashes are really
just visual noise as far as I'm concerned.

>> that may have been needed in Perl, but aren't helpful here.  Take them out
>> to reduce slightly the visual noise.
>
> No idea if Perl actually requires, but, at least for me, I do prefer to
> see all special characters properly escaped with a backslash. This way,
> it is a lot clearer that what it is expecting is a string, instead of
> using something that may affect regex processing.

I guess my point is that, in the given cases, the characters in question
*aren't* special.

>> -        param = KernRe(r'[\[\)].*').sub('', param, count=1)
>> +        param = KernRe(r'[)[].*').sub('', param, count=1)
>
> This one, for instance, IMHO looks a lot worse for my eyes to understand
> that there is a "[" that it is not an operator, but instead a string.
> The open close parenthesis also looks weird. My regex-trained eyes think
> that this would be part of a capture group.

...and mine say "that's in [brackets] why are you escaping it?" :)

>>          if dtype == "" and param.endswith("..."):
>>              if KernRe(r'\w\.\.\.$').search(param):
>> @@ -405,7 +405,7 @@ class KernelDoc:
>>  
>>          for arg in args.split(splitter):
>>              # Strip comments
>> -            arg = KernRe(r'\/\*.*\*\/').sub('', arg)
>> +            arg = KernRe(r'/\*.*\*/').sub('', arg)
>
> A pattern like /..../ is a standard way to pass search group with Regex
> on many languages and utils that accept regular expressions like the
> sed command. Dropping the backslash here IMHO makes it confusing ;-)

...but it is definitely not any such in Python and never has been, so
escaping slashes looks weird and makes the reader wonder what they are
missing.

> Seriously, IMHO this patch makes a lot worse to understand what brackets,
> parenthesis and dots are strings, and which ones are part of the regex
> syntax. 

So I guess I won't fight this one to the death, but I really do
disagree.  Writing regexes in a non-canonical style just makes it harder
for anybody else who comes along to figure out what is going on; it
certainly made it harder for me.

Thanks,

jon