[issue40016] Clarify flag case in `re` module docstring

[Terry J. Reedy]

Terry J. Reedy <tjreedy at udel.edu> added the comment:

The docstring line in question is
  (?aiLmsux) Set the A, I, L, M, S, U, or X flag for the RE (see below).

This is exceptional in that other syntaxes in the special characters list use lower case only for syntax variables (m, n, name, id/name, yes, no).  Here, each letter is a separate and literal special character.  (Also exceptional is that the syntax given is illegal, as 'a', 'L', and 'u' are mutually exclusive.)

The corresponding doc entry starts
"(One or more letters from the set 'a', 'i', 'L', 'm', 's', 'u', 'x'.)
... the letters set the corresponding flags:" followed by 6 more lines.

I suggest the following as the replacement here (followed by more 'below').
  (?aiLmsux) The letters set the corresponding flags defined below.

I think 'letters' pretty clearly refers to 'a', 'i', ..., and 'x' as given, and that each 'corresponds' to and sets a flag that is a separate entity.

The more complicated inline flags syntax, "(?aiLmsux-imsx:...)", is omitted from the docstring.  Perhaps this is intentional.

The flag constants are currently introduced by
Some of the functions in this module takes flags as optional parameters:

My suggested more accurate and expanded replacement:
"Each function other than purge and escape can take an optional 'flags'  argument consisting of one or more of the following module constants, joined by "|".  A, L, and U are mutually exclusive."

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue40016>
_______________________________________