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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Fri, 01 Aug 2025 08:21:49 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> 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?

I caught several issues in the past due to the lack of it. Don't
recall the specific cases, but using reserved symbols without
backslashes have giving me enough headaches.

Yet, see POSIX rules for some cases:

	https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_03

like this one:

	"The character sequences "[.", "[=", and "[:" shall be special
	 inside a bracket expression"

Basically, if you don't know exactly what you're doing, and just
place special characters there without extra case, you may be
in serious troubles. And see, this is just for BRE (basic regular
expressions). There are also other weirdness with ERE (extended
regular expressions):

	"The <period>, <left-square-bracket>, <backslash>, and 
	 <left-parenthesis> shall be special except when used 
	 in a bracket expression"

> > 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.

They are special in the sense that we're using characters that
have meanings in regular expressions and even placing them on
a random order may cause POSIX violations (and eventually cause
troubles if, for instance, we need to use "regex" instead of "re",
or if someone fixes python native "re" to be more POSIX compliant.

> >> -        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?" :)

Heh, all those years writing and reviewing kernel code, for me
seeing unmatched parenthesis/brackets really bugs me... perhaps
it starts some sort of TOC syndrome ;-)

Perhaps one alternative would be to have a separate var, like:

	# Before touching this, see:
	# https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04
	# As some char sequences inside brackets have special meanings
	escape_chars = ")["

	param = KernRe(rf'[{escape_chars}].*').sub('', param, count=1)  

or to use re_escape().

> >>          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.

After re-reading, this specific change is actually ok, but yeah, I
still need to read it twice or three times, as on sed, perl and other
languages that are more POSIX compliant, /re/ means a regex delimiter:

	https://en.wikipedia.org/wiki/Regular_expression

> > 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.

Heh, for me, my main concerns are:
- unmatched brackets/parenthesis
- POSIX violations - it may work today, but future Python versions
  that fix "re" module will cause regressions. It is also annoying
  to write/understand regex that only works on Python.

I can live with the other ones.

Thanks,
Mauro