RFR: 8199594: Add doc describing how (?x) ignores spaces in character classes [v2]

[Stuart Marks]

On Mon, 19 Apr 2021 22:12:30 GMT, Ian Graves <igraves at openjdk.org> wrote:

>> Clarifying note on comments mode to explicitly note that whitespace within character classes is ignored.
>
> Ian Graves has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Adding differences to Perl 5 note

A few minor wording adjustments. Please update the CSR accordingly and I'll review it too.

src/java.base/share/classes/java/util/regex/Pattern.java line 762:

> 760:  *    character classes. In this class, whitespace inside of character classes
> 761:  *    must be escaped to be considered as part of the regular expression when in
> 762:  *    comments mode.  </p></li>

Editorial: the run of italicized words makes this a bit hard to follow. Suggest:

    In Perl, <i>free-spacing mode</i> (which is called <i>comments mode</i> in this class)

src/java.base/share/classes/java/util/regex/Pattern.java line 832:

> 830:      * <p> Note that comments mode ignores whitespace within a character class
> 831:      * contained in a pattern string. Such whitespace needs to be escaped
> 832:      * in order to be treated as if comments mode were not enabled. </p>

I think this is good, but 1) it would probably be better placed in the "In this mode" paragraph above, around line 825; and 2) it's normative so it shouldn't say "Note that" (which makes it sound informative).

I'd also reword the second sentence a bit, something like

    Such whitespace needs to be escaped in order to be considered significant.

-------------

Changes requested by smarks (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/3577