Re: [PATCH 03/12] docs: kdoc: backslashectomy in kdoc_parser

[Jonathan Corbet <corbet@lwn.net>]

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

> Em Thu, 31 Jul 2025 18:13:17 -0600
> Jonathan Corbet <corbet@lwn.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