<i18n dev> RFR: JDK-8285932 Implementation of JEP 430 String Templates (Preview) [v28]

[Roger Riggs]

On Mon, 21 Nov 2022 17:43:16 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:
> 
>   Seal Digits

Javadoc suggestions around readability, linking.

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 stringTemplate} object.

When reading the javadoc, I expected the type name, not the variable name.
Suggestion:

     * supplied {@link StringTemplate StringTemplate} object.

src/java.base/share/classes/java/lang/template/StringTemplate.java line 52:

> 50:  * given by the template expression.
> 51:  * <p>
> 52:  * For example, the following code contains a template expression that uses the template

Though this is trying to explain the general mechanism, it might be more useful to readers to start with the most common use case, that of using a string processor. Swapping the order of the examples possibly.

src/java.base/share/classes/java/lang/template/StringTemplate.java line 63:

> 61:  * {@code fragments} will be equivalent to {@code List.of("", " + ", " = ", "")},
> 62:  * which includes the empty first and last fragments. {@code values} will be the
> 63:  * equivalent of {@code List.of(10, 20, 30)}.

Find a way to capitalize the first word of the sentence.
Suggestion:

 * The value of {@code fragments} will be equivalent to {@code List.of("", " + ", " = ", "")},
 * which includes the empty first and last fragments. The {@code values} will be the
 * equivalent of {@code List.of(10, 20, 30)}.

src/java.base/share/classes/java/lang/template/StringTemplate.java line 66:

> 64:  * <p>
> 65:  * The following code contains a template expression with the same template but a
> 66:  * different template processor:

Suggestion:

 * The following code contains a template expression with the same template but a
 * string template processor:

src/java.base/share/classes/java/lang/template/StringTemplate.java line 75:

> 73:  * produced that returns the same lists from {@link StringTemplate#fragments()} and
> 74:  * {@link StringTemplate#values()} as shown above. The {@link StringTemplate#STR} template
> 75:  * processor uses these lists to yield an interpolated string. {@code s} will be equivalent to

Suggestion:

 * processor uses these lists to yield an interpolated string. The value of {@code s} will be equivalent to

src/java.base/share/classes/java/lang/template/StringTemplate.java line 319:

> 317:      * This {@link StringProcessor} instance is conventionally used for the string interpolation
> 318:      * of a supplied {@link StringTemplate}.
> 319:      * <p>

It should be mentioned that the string representations are created as if invoking {@link String#valueOf}.
An perhaps a link/@see to `FMT` for control over formatting.  

Also include it in the javadoc for `interpolate`.

src/java.base/share/classes/java/lang/template/package-info.java line 57:

> 55:  *{@link java.lang.template.StringTemplate}. The end result of the process template
> 56:  * expression is the value that is produced by invoking the processor's
> 57:  *{@link java.lang.template.ValidatingProcessor#process(StringTemplate)}

I would reduce the use of "proper", it should be sufficient to describe them without the qualifier.
The single use of "improper" is fine to warn of compilation errors.

Also, add a space between "*" and "{".

src/java.base/share/classes/java/lang/template/package-info.java line 61:

> 59:  * improper processor arguments result in compilation errors.
> 60:  * <p>
> 61:  * In the example, {@code STR."The result of adding \{x} and \{y} is \{x + y}."},

Maybe avoid the repetition of the example.
Suggestion:

 * In the example above,

src/java.base/share/classes/java/lang/template/package-info.java line 76:

> 74:  * String literals and text blocks can be used as proper processor arguments as
> 75:  * well. This is automatically facilitated by the Java compiler converted the
> 76:  * strings to {@link java.lang.template.StringTemplate StringTemplate} using the

Suggestion:

 * well. This is automatically facilitated by the Java compiler converting the
 * strings to {@link java.lang.template.StringTemplate StringTemplate} using the

src/java.base/share/classes/java/lang/template/package-info.java line 79:

> 77:  * {@link java.lang.template.StringTemplate#of(String)} method.
> 78:  * <p>
> 79:  * Users can create their own template processors by implementing either

Suggestion:

 * Users can create their own template processors by implementing one of

src/java.base/share/classes/java/lang/template/package-info.java line 83:

> 81:  * {@link java.lang.template.TemplateProcessor} or
> 82:  * {@link java.lang.template.StringProcessor} interfaces.
> 83:  * See {@link java.lang.template.ValidatingProcessor} for examples and details.

I would give the reader a firm what to read next suggestion.
It may be useful to mention and link to the `FMT` processor as a way to control the formatting of the values.
Suggestion:

 * For more examples and details see  {@link java.lang.template.StringTemplate} and 
 * {@link java.lang.template.ValidatingProcessor}.

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

> 62:  *
> 63:  * @implSpec Since, values are found within the string template, argument indexing
> 64:  * specifiers are unsupported.

What is the behavior of a format that references an index?  Ignored, throw?
I can see an argument for simplicity, but the values are a sequential list similar to that of a varargs call to format("xx", x, y, z, ...) so it can be well defined to what value an index in the format refers.

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

> 194:      * <a href="../../util/Formatter.html#syntax">format specifier</a>.
> 195:      * StringTemplate expressions without a preceeding specifier, use "%s" by
> 196: 

Its worth specifying the locale that is used by FMT, is it `Locale.ROOT`?
If it is `Locale.default`, the results may vary from run to run.

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

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