On Mon, 11 Dec 2023 18:54:25 GMT, Naoto Sato <na...@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
