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

[Roger Riggs]

On Wed, 16 Nov 2022 20:33:50 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 two additional commits since the last revision:
> 
>  - Requested changes #8
>  - Update StringTemplate javadoc

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

> 85:  * alternative to using string template expressions.
> 86:  * {@snippet :
> 87:  * StringTemplate st = RAW."\{x} + \{y} = \{x + y}";

RAW and STR are used in similar ways in the examples but RAW produces a compilation error.
Somewhere obvious there should be an API note that RAW needs an explicit import static whereas STR is imported automatically.

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

> 118:      * String student = "Mary";
> 119:      * String teacher = "Johnson";
> 120:      * StringTemplate st = RAW."The student \{student} is in \{teacher}'s class room.";

typo?  "class room" -> "classroom" or just "class"
Also below.

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

> 174:      * String result2 = RAW."The student \{student} is in \{teacher}'s class room.".process(STR); // @highlight substring="process"
> 175:      * }
> 176:      * produces an equivalent result for both {@code result1} and {@code result2}.

Capitalize this sentence.  "Produces"...

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

> 186:      * @throws NullPointerException if processor is null
> 187:      *
> 188:      * @implNote The default implementation invokes the processor's process

too many processes...
Perhaps:

... `invokes the {@code processor.process(this)} method.`

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

> 296:      *
> 297:      * @throws NullPointerException if sts is null or if any of the elements are null
> 298:      * @throws RuntimeException if sts has zero elements

The RuntimeException may be a leftover; TemplateSupport.combine(sts) allows there to be zero elements.
(And RuntimeException is too general for the described case, perhaps IllegalArgumentException)

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

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