<i18n dev> RFR: 8319986: Invalid/inconsistent description and example for DateFormat [v3]

[Roger Riggs]

On Tue, 14 Nov 2023 17:14:06 GMT, Naoto Sato <naoto at openjdk.org> wrote:

>> src/java.base/share/classes/java/text/DateFormat.java line 120:
>> 
>>> 118:  * result; from {@link #SHORT} to {@link #MEDIUM} to {@link #LONG} to {@link #FULL}. The exact result depends
>>> 119:  * on the locale, but generally:
>>> 120:  * <ul><li>{@link #SHORT} is the shortest and mainly numeric, such as {@code 12.13.52} or {@code 3:30pm}
>> 
>> Not sure if we want to update the descriptions of all options, but if we want to be consistent, here's a suggestion, how about:
>>   {@link #SHORT} is a concise format using numeric digits, for example, {@code 12.13.52} or {@code 3:30pm}
>>   {@link #MEDIUM} provides more detail, such as {@code Jan 12, 1952}
>>   {@link #LONG} is a comprehensive format, such as {@code January 12, 1952} or {@code 3:30:32pm}
>>   {@link #FULL} provides a complete date representation, such as
>>   
>>   "pretty completely" is a bit casual :-)
>
> Thanks for the feedback, Joe. I think I would rather keep the description somewhat abstract, simply mentioning the formatted output is `SHORT` <= `MEDIUM` <= `LONG` <= `FULL` in length-wise. As it is noted in the previous sentence, it is pretty much locale-dependent.
> I simply replaced that casual wording with "the longest" for consistency.

Is there any value in mentioning that MEDIUM format typically uses abbreviations.
Whereas the LONG and FULL format typically does not use abbreviations.  (For months)

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16645#discussion_r1393041408