On Mon, 13 Sep 2021 14:23:59 GMT, Hannes Wallnöfer <hann...@openjdk.org> wrote:
>> Pavel Rappo has updated the pull request incrementally with one additional
>> commit since the last revision:
>>
>> Remove trailing whitespace to satisfy jcheck
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/snippet/Parser.java
> line 297:
>
>> 295: // corresponding positions in snippet source.
>> 296: final String value = regex.get().value();
>> 297: assert value.equals(Pattern.compile(value).pattern()) :
>> value;
>
> What is the purpose of this assertion, and when would it ever fail?
I think that this assertion is misguided. The assertion I wanted to make should
be a test, which I will provide shortly. Thanks for directing my attention to
it.
The purpose of that assertion was to encode the following factual statement:
the value of the regex attribute is WYSIWYG. That is, javadoc interprets that
value as is: characters or sequences thereof are treated literally. Compare
this with Java source or jshell, where escape sequences are recognized:
jshell> Pattern.compile("name\t=\t"value"")
$1 ==> name = "value"
Why is it important? Because of error messages. Knowing how a regex is
represented in source allows javadoc to map the index passed in an instance of
`java.util.regex.PatternSyntaxException` back to regex source so as to adjust
the caret position in a diagnostic message should the regex be invalid.
-------------
PR: https://git.openjdk.java.net/jdk/pull/4795
