On Fri, 26 Jan 2024 21:16:47 GMT, Archie Cobbs <aco...@openjdk.org> wrote:
>> src/java.base/share/classes/java/text/MessageFormat.java line 558: >> >>> 556: * @implSpec The implementation in {@link MessageFormat} returns a >>> string >>> 557: * that can be used to create a new instance that is semantically >>> equivalent >>> 558: * to this instance. >> >> The "can be used to create" seems conditional. Perhaps it can be worded as >> an assertion that can be tested. >> Suggestion: >> >> * @implSpec A new MessageFormat created from the string returned from >> the implementation of >> * `MessageFormat.toPattern()` is semantically equivalent to this >> instance. > >> The "can be used to create" seems conditional. > > It is conditional - in the sense that you don't _have_ to use it to create a > new instance of `MessageFormat`. You can also use it for something else, in > other words. > > But I also understand how it comes across as a bit wishy-washy... > > Hmm, what do you think about this wording? > > > @implSpec The implementation in {@link MessageFormat} returns a string that, > when passed to the {@link MessageFormat(String)} constructor, produces an > instance that is semantically equivalent to this instance. Not sure which wording will ultimately be used, but if the wording ends up including the constructor, it's probably worth mentioning the `applyPattern` method as well. ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/17416#discussion_r1468163934