On Mon, 21 Nov 2022 17:43:16 GMT, Jim Laskey <jlas...@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
