Merge

src/java.base/share/classes/java/lang/Character.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2002, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2002, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -35,35 +35,29 @@ import jdk.internal.misc.VM;
 
 /**
  * The {@code Character} class wraps a value of the primitive
- * type {@code char} in an object. An object of type
+ * type {@code char} in an object. An object of class
  * {@code Character} contains a single field whose type is
  * {@code char}.
  * <p>
- * In addition, this class provides several methods for determining
- * a character's category (lowercase letter, digit, etc.) and for converting
- * characters from uppercase to lowercase and vice versa.
+ * In addition, this class provides a large number of static methods for
+ * determining a character's category (lowercase letter, digit, etc.)
+ * and for converting characters from uppercase to lowercase and vice
+ * versa.
+ *
+ * <h3><a id="conformance">Unicode Conformance</a></h3>
  * <p>
- * Character information is based on the Unicode Standard, version 11.0.0.
+ * The fields and methods of class {@code Character} are defined in terms
+ * of character information from the Unicode Standard, specifically the
+ * <i>UnicodeData</i> file that is part of the Unicode Character Database.
+ * This file specifies properties including name and category for every
+ * assigned Unicode code point or character range. The file is available
+ * from the Unicode Consortium at
+ * <a href="http://www.unicode.org">http://www.unicode.org</a>.
  * <p>
- * The methods and data of class {@code Character} are defined by
- * the information in the <i>UnicodeData</i> file that is part of the
- * Unicode Character Database maintained by the Unicode
- * Consortium. This file specifies various properties including name
- * and general category for every defined Unicode code point or
- * character range.
- * <p>
- * The file and its description are available from the Unicode Consortium at:
- * <ul>
- * <li><a href="http://www.unicode.org">http://www.unicode.org</a>
- * </ul>
- * <p>
- * The code point, U+32FF, is reserved by the Unicode Consortium
- * to represent the Japanese square character for the new era that begins
- * May 2019. Relevant methods in the Character class return the same
- * properties as for the existing Japanese era characters (e.g., U+337E for
- * "Meizi"). For the details of the code point, refer to
- * <a href="http://blog.unicode.org/2018/09/new-japanese-era.html">
- * http://blog.unicode.org/2018/09/new-japanese-era.html</a>.
+ * The Java SE 12 Platform uses character information from version 11.0
+ * of the Unicode Standard, plus the Japanese Era code point,
+ * {@code U+32FF}, from the first version of the Unicode Standard
+ * after 11.0 that assigns the code point.
  *
  * <h3><a id="unicode">Unicode Character Representations</a></h3>
  *
@@ -9495,7 +9489,7 @@ class Character implements java.io.Serializable, Comparable<Character> {
      * character in a Java identifier.
      * <p>
      * A character may start a Java identifier if and only if
-     * one of the following is true:
+     * one of the following conditions is true:
      * <ul>
      * <li> {@link #isLetter(char) isLetter(ch)} returns {@code true}
      * <li> {@link #getType(char) getType(ch)} returns {@code LETTER_NUMBER}
@@ -9524,8 +9518,8 @@ class Character implements java.io.Serializable, Comparable<Character> {
      * Determines if the specified character may be part of a Java
      * identifier as other than the first character.
      * <p>
-     * A character may be part of a Java identifier if and only if any
-     * of the following are true:
+     * A character may be part of a Java identifier if and only if one
+     * of the following conditions is true:
      * <ul>
      * <li>  it is a letter
      * <li>  it is a currency symbol (such as {@code '$'})
@@ -9667,7 +9661,7 @@ class Character implements java.io.Serializable, Comparable<Character> {
      * identifier as other than the first character.
      * <p>
      * A character may be part of a Java identifier if any of the following
-     * are true:
+     * conditions are true:
      * <ul>
      * <li>  it is a letter
      * <li>  it is a currency symbol (such as {@code '$'})
@@ -9704,7 +9698,7 @@ class Character implements java.io.Serializable, Comparable<Character> {
      * identifier as other than the first character.
      * <p>
      * A character may be part of a Java identifier if any of the following
-     * are true:
+     * conditions are true:
      * <ul>
      * <li>  it is a letter
      * <li>  it is a currency symbol (such as {@code '$'})
@@ -9715,7 +9709,7 @@ class Character implements java.io.Serializable, Comparable<Character> {
      * <li>  it is a non-spacing mark
      * <li> {@link #isIdentifierIgnorable(int)
      * isIdentifierIgnorable(codePoint)} returns {@code true} for
-     * the character
+     * the code point
      * </ul>
      *
      * @param   codePoint the character (Unicode code point) to be tested.

src/java.base/share/classes/java/time/chrono/JapaneseEra.java

@@ -88,15 +88,33 @@ import sun.util.calendar.CalendarDate;
 /**
  * An era in the Japanese Imperial calendar system.
  * <p>
- * This class defines the valid eras for the Japanese chronology.
- * Japan introduced the Gregorian calendar starting with Meiji 6.
- * Only Meiji and later eras are supported;
- * dates before Meiji 6, January 1 are not supported.
- * The number of the valid eras may increase, as new eras may be
- * defined by the Japanese government. Once an era is defined,
- * future versions of the platform may add a singleton instance
- * for it. The defined era is expected to have a consecutive integer
- * associated with it.
+ * The Japanese government defines the official name and start date of
+ * each era. Eras are consecutive and their date ranges do not overlap,
+ * so the end date of one era is always the day before the start date
+ * of the next era.
+ * <p>
+ * The Java SE Platform supports all eras defined by the Japanese government,
+ * beginning with the Meiji era. Each era is identified in the Platform by an
+ * integer value and a name. The {@link #of(int)} and {@link #valueOf(String)}
+ * methods may be used to obtain a singleton instance of {@code JapaneseEra}
+ * for each era. The {@link #values()} method returns the singleton instances
+ * of all supported eras.
+ * <p>
+ * For convenience, this class declares a number of public static final fields
+ * that refer to singleton instances returned by the {@link #values()} method.
+ *
+ * @apiNote
+ * The fields declared in this class may evolve over time, in line with the
+ * results of the {@link #values()} method. However, there is not necessarily
+ * a 1:1 correspondence between the fields and the singleton instances.
+ *
+ * @apiNote
+ * The Japanese government may announce a new era and define its start
+ * date but not its official name. In this scenario, the singleton instance
+ * that represents the new era may return a name that is not stable until
+ * the official name is defined. Developers should exercise caution when
+ * relying on the name returned by any singleton instance that does not
+ * correspond to a public static final field.
  *
  * @implSpec
  * This class is immutable and thread-safe.
@@ -199,14 +217,18 @@ public final class JapaneseEra
     //-----------------------------------------------------------------------
     /**
      * Obtains an instance of {@code JapaneseEra} from an {@code int} value.
+     * <ul>
+     * <li>The value {@code 1} is associated with the 'Showa' era, because
+     * it contains 1970-01-01 (ISO calendar system).</li>
+     * <li>The values {@code -1} and {@code 0} are associated with two earlier
+     * eras, Meiji and Taisho, respectively.</li>
+     * <li>A value greater than {@code 1} is associated with a later era,
+     * beginning with Heisei ({@code 2}).</li>
+     * </ul>
      * <p>
-     * The {@link #SHOWA} era that contains 1970-01-01 (ISO calendar system) has the value 1.
-     * Later era is numbered 2 ({@link #HEISEI}). Earlier eras are numbered 0 ({@link #TAISHO}),
-     * -1 ({@link #MEIJI}), only Meiji and later eras are supported.
-     * <p>
-     * In addition to the known era singletons, values for additional
-     * eras may be defined. Those values are the {@link Era#getValue()}
-     * of corresponding eras from the {@link #values()} method.
+     * Every instance of {@code JapaneseEra} that is returned from the {@link #values()}
+     * method has an int value (available via {@link Era#getValue()} which is
+     * accepted by this method.
      *
      * @param japaneseEra  the era to represent
      * @return the {@code JapaneseEra} singleton, not null