RFR: 8320919: Clarify Locale related system properties

[Justin Lu]

On Mon, 11 Dec 2023 18:54:25 GMT, Naoto Sato <naoto at openjdk.org> wrote:

> This is a doc change to clarify what the `Default Locale` is, and how it is established during the system startup using the system properties. Those locale-related system properties have existed since the early days of Java, but have never been publicly documented before. It is also the intention of this PR to clarify those system properties and how they are overridden. A corresponding CSR has been drafted.

LGTM; left some minor wording comments.

src/java.base/share/classes/java/util/Locale.java line 264:

> 262:  * <h3><a id="default_locale">Default Locale</a></h3>
> 263:  *
> 264:  * <p>The default Locale is provided mainly for the locale-sensitive methods if no

Suggestion:

 * <p>The default Locale is mainly provided for any locale-sensitive methods if no

src/java.base/share/classes/java/util/Locale.java line 270:

> 268:  * <ol>
> 269:  * <li>The locale-related system properties listed below are established from the
> 270:  * host environment. Some system properties (except for {@code user.language}) may

IIUC, should it be _all_ system properties, not _some_ if we are defining the single exception?

src/java.base/share/classes/java/util/Locale.java line 301:

> 299:  * is unparsable, it is ignored. The overriding values of other properties are not
> 300:  * checked for syntax or validity and are used directly in the default Locale.
> 301:  * (Typically, system property values can be provided using the {@code -D} command-line

Do these last two sentences need to be enclosed in a parentheses? It seems pretty important as it is the main way to override the properties via command-line.

src/java.base/share/classes/java/util/Locale.java line 307:

> 305:  * "foobarbaz".)
> 306:  * </li>
> 307:  * <li>The default {@code Locale} instance is constructed from these system

Might read better as "... is constructed from the values of these system properties."

src/java.base/share/classes/java/util/Locale.java line 317:

> 315:  * If the default Locale is changed with {@link #setDefault(Locale)}, the corresponding
> 316:  * system properties are not altered. It is not recommended that applications read
> 317:  * those system properties and parse/interpret them as their values may be out of sync.

Suggestion:

 * these system properties and parse/interpret them as their values may be out of sync.

src/java.base/share/classes/java/util/Locale.java line 321:

> 319:  * <p>There are finer-grained default Locales specific for each {@link Locale.Category}.
> 320:  * These category specific default Locales can be queried by {@link #getDefault(Category)},
> 321:  * and set by {@link #setDefault(Category, Locale)}. Constructions of these category

Suggestion:

 * and set by {@link #setDefault(Category, Locale)}. Construction of these category

src/java.base/share/classes/java/util/Locale.java line 327:

> 325:  * the value of the {@code user.language.display} system property will be used in the
> 326:  * {@code language} part of the default Locale for {@link Locale.Category#DISPLAY}
> 327:  * category. In the absence of category specific system properties the "category-less"

Suggestion:

 * category. In the absence of category specific system properties, the "category-less"

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

PR Review: https://git.openjdk.org/jdk/pull/17065#pullrequestreview-1776299148
PR Review Comment: https://git.openjdk.org/jdk/pull/17065#discussion_r1423205213
PR Review Comment: https://git.openjdk.org/jdk/pull/17065#discussion_r1423205166
PR Review Comment: https://git.openjdk.org/jdk/pull/17065#discussion_r1423206857
PR Review Comment: https://git.openjdk.org/jdk/pull/17065#discussion_r1423209519
PR Review Comment: https://git.openjdk.org/jdk/pull/17065#discussion_r1423205137
PR Review Comment: https://git.openjdk.org/jdk/pull/17065#discussion_r1423205118
PR Review Comment: https://git.openjdk.org/jdk/pull/17065#discussion_r1423205082