RFR: JDK-8285932 Implementation of JEP 430 String Templates (Preview) [v42]

[Roger Riggs]

On Mon, 27 Feb 2023 12:47:03 GMT, Jim Laskey <jlaskey at openjdk.org> wrote:

>> Enhance the Java programming language with string templates, which are similar to string literals but contain embedded expressions. A string template is interpreted at run time by replacing each expression with the result of evaluating that expression, possibly after further validation and transformation. This is a [preview language feature and API](http://openjdk.java.net/jeps/12).
>
> Jim Laskey has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Tighten up reporting of string template errors (fewer messages)

src/java.base/share/classes/java/lang/template/ProcessorLinkage.java line 37:

> 35: 
> 36: /**
> 37:  * Policies using this additional interface have the flexibility to specialize

Since it is 'sealed' it may clarify the use to say "Builtin policies"...

src/java.base/share/classes/java/lang/template/StringProcessor.java line 49:

> 47:  * @implNote Implementations using {@link StringProcessor} are equivalent to implementations using
> 48:  * {@code TemplateProcessor<String>} or {@code ValidatingProcessor<String, RuntimeException>},
> 49:  * however, StringProcessor is cleaner and easier to understand.

Split into two sentences.

Suggestion:

 * {@code TemplateProcessor<String>} or {@code ValidatingProcessor<String, RuntimeException>}.
 * However, StringProcessor is cleaner and easier to understand.

src/java.base/share/classes/java/lang/template/StringProcessor.java line 58:

> 56:     /**
> 57:      * Constructs a {@link String} based on the template fragments and values in the
> 58:      * supplied {@link StringTemplate} object.

Some inconsistency in the use of link/linkplain and the capitalization of stringTemplate, the instance or the type.
(As compared to TemplateProcessor.process(stringTemplate))
Suggestion:

     * supplied {@link StringTemplate} object.

src/java.base/share/classes/java/util/FormatProcessor.java line 42:

> 40:  * {@link Formatter} specifications and values found in the {@link StringTemplate}.
> 41:  * Unlike {@link Formatter}, {@link FormatProcessor} uses the value from the
> 42:  * embedded expression that immediately follows, no whitespace, after the

Suggestion:

 * embedded expression that immediately follows, without whitespace, the

src/java.base/share/classes/java/util/FormatProcessor.java line 66:

> 64:  * <p>
> 65:  * {@link FormatProcessor}  format specification uses and exceptions are the same as
> 66:  * those of {@link Formatter}.

Suggestion:

 * The {@link FormatProcessor} format specification uses and exceptions are the same as
 * those of {@link Formatter}.

src/java.base/share/classes/java/util/FormatProcessor.java line 80:

> 78:  * int x = 10;
> 79:  * int y = 20;
> 80:  * String result = thaiFMT."%d\{x} + %d\{y} = %d\{x + y}";

The inclusion of format specifiers that yield the same results as the default (%s) may mislead developers into thinking they need the format specifier. Making the examples look more complicated than necessary.
Can the examples, show customized output.

Suggestion:

 * String result = thaiFMT."%d{x} + %d{y} = %d{x + y}";

src/java.base/share/classes/java/util/FormatProcessor.java line 134:

> 132:      * format string from the fragments, gathers up the values and
> 133:      * evaluates the expression
> 134:      * {@code new Formatter(locale).format(format, values).toString()}.

Should this be described using the "as if"... phrasing to avoid a literal requirement in the spec that is inflexible?

src/java.base/share/classes/java/util/FormatProcessor.java line 175:

> 173:      * {@link FormatProcessor#FMT} ({@code static final FormatProcessor}).
> 174:      * <p>
> 175:      * Other {@link FormatProcessor} can be specialized if stored as static final.

Suggestion:

     * Other {@link FormatProcessor}s can be specialized if stored as a static final.

src/java.base/share/classes/java/util/FormatProcessor.java line 187:

> 185:      * @throws  IllegalFormatException
> 186:      *          If a format specifier contains an illegal syntax, a format
> 187:      *          specifier that is incompatible with the given arguments,

Suggestion:

     *          specifier is incompatible with the given arguments,

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

PR: https://git.openjdk.org/jdk/pull/10889