On Tue, 5 Sep 2023 19:50:23 GMT, Naoto Sato <na...@openjdk.org> wrote:
>> src/java.base/share/classes/java/text/ListFormat.java line 48:
>>
>>> 46: * List Patterns</a>.
>>> 47: * <p>
>>> 48: * Three types of concatenation are provided: {@link Type#STANDARD
>>> STANDARD},
>>
>> A "Type" and "Style" together make up a specific pattern. It might be good
>> to introduce the term "List Patterns" here first, that is, moving the
>> introduction of patterns to the class description from the 1-arg getInstance
>> method. once we have the terms established, we can then delve into the
>> specific cases "types" and "styles" represent. Something like:
>>
>> <h2>List Patterns</h2>
>> List Patterns are rules that define how a series or list is formed ...
>> (include the description for the getInstance(String[] patterns) here)
>>
>> <h2>Standard Patterns</h2>
>> {@code ListFormat} supports a few pre-defined patterns with a combination of
>> Type (link) and Style(link). Types and Styles are defined as follows.
>>
>> <h3>Type</h3>
>> {@link Type#STANDARD STANDARD}: a simple list with conjunction "and";
>>
>> ...
>>
>> <h3>Style</h3>
>> {@link Style#FULL FULL}: uses the conjunction word such as "and";
>>
>> {@link Style#SHORT SHORT}: uses the shorthand of the conjunction word, "&"
>> (ampersand) for "and" for example;
>>
>> {@link Style#NARROW NARROW}: uses no conjunction word.
>>
>> For example, a combination of {@link Type#STANDARD STANDARD} and {@link
>> Style#FULL FULL} forms an inclusive list pattern.
>
> I think that Type/Style/Locale forming a specific pattern is an
> implementation detail, so I would not describe it in the spec (although as
> you say they form a specific pattern in the impl). It could be that an impl
> of 3-arg getInstance() can be independent of patterns described in 1-arg
> getInstance().
Type and Style select a pattern defined for the locale. (for the zero arg and
three arg getInstance methods).
I think I would avoid the term "concatenation", the type defines a pattern that
contains punctuation and connecting words. The style selects among the full,
short, and narrow patterns.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/15130#discussion_r1316362486
