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

[Roger Riggs]

On Fri, 18 Nov 2022 14:10:11 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:
> 
>   Typo

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 the dominance of {@link String} producing template processors supercedes the redundancy.

Amusing to read...  
Perhaps just,  "however, StringProcessor is clearer and easier to understand".

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

> 33: /**
> 34:  * {@link StringTemplate} is the run-time representation of a string template or
> 35:  * text block template in a template expression.

Can the link to the JLS 15.8.6 be included earlier so the definition of "template expression" isn't hanging until the end of the class javadoc.

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

> 113: public interface StringTemplate {
> 114:     /**
> 115:      * Returns s list of fragment literals for this {@link StringTemplate}.

Suggestion:

     * Returns a list of fragment literals for this {@link StringTemplate}.

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

> 153:      * For better visibility and when practical, it is recommended that users use the
> 154:      * {@link StringTemplate#STR} processor instead of invoking the
> 155:      * {@link StringTemplate#interpolate()} method directly.

Removing "users use"...

Suggestion:

     * For better visibility and when practical, it is recommended to use the
     * {@link StringTemplate#STR} processor instead of invoking the
     * {@link StringTemplate#interpolate()} method.

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

> 204:      * @param stringTemplate  the {@link StringTemplate} to represent
> 205:      *
> 206:      * @return diagnostic string representing the supplied templated string

Suggestion:

     * @return diagnostic string representing the supplied string template

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

> 298:      * {@link StringTemplate StringTemplates}.
> 299:      *
> 300:      * @param stringTemplates  one or more {@link StringTemplate}

Suggestion:

     * @param stringTemplates  zero or more {@link StringTemplate}


Also the comment in `TemplateSupport.combine` should say zero or more.

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

> 315:     /**
> 316:      * The {@link StringProcessor} instance conventionally used for the string interpolation
> 317:      * of a supplied {@link StringTemplate}.

Suggestion:

     * The {@link StringProcessor} instance is conventionally used for the string interpolation
     * of a supplied {@link StringTemplate}.

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

> 332:     /**
> 333:      * The {@link TemplateProcessor} instance conventionally used to indicate that the
> 334:      * processing of the {@link StringTemplate} is to be deferred to a later time. Deferred

Suggestion:

     * The {@link TemplateProcessor} instance is conventionally used to indicate that the
     * processing of the {@link StringTemplate} is to be deferred to a later time. Deferred

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

> 25: 
> 26: /**
> 27:  * Provides support for string templates and template processors.

Not just support...

String templates are provided by {@link StringTemplate} and supporting interfaces and classes.
It might also be helpful to include a link to the JLS 15.8.6 Template Expression spec.

A brief example here (drawn from the JEP or StringTemplate would provide a good hook for the reader to get started.

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

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