RFR: 8266666: Implementation for snippets [v23]

[Pavel Rappo]

On Mon, 13 Sep 2021 14:23:59 GMT, Hannes Wallnöfer <hannesw at 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