8254275: [valhalla/jep390] Revise "value-based class" & apply to wrappers

Reviewed-by: mchung, rriggs

Author: Dan Smith

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

@@ -41,13 +41,19 @@
  * {@code boolean} in an object. An object of type
  * {@code Boolean} contains a single field whose type is
  * {@code boolean}.
- * <p>
- * In addition, this class provides many methods for
+ *
+ * <p>In addition, this class provides many methods for
  * converting a {@code boolean} to a {@code String} and a
  * {@code String} to a {@code boolean}, as well as other
  * constants and methods useful when dealing with a
  * {@code boolean}.
  *
+ * <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
+ * class; programmers should treat instances that are
+ * {@linkplain #equals(Object) equal} as interchangeable and should not
+ * use instances for synchronization, or unpredictable behavior may
+ * occur.
+ *
  * @author  Arthur van Hoff
  * @since   1.0
  */

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

@@ -48,6 +48,12 @@
  * byte}, as well as other constants and methods useful when dealing
  * with a {@code byte}.
  *
+ * <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
+ * class; programmers should treat instances that are
+ * {@linkplain #equals(Object) equal} as interchangeable and should not
+ * use instances for synchronization, or unpredictable behavior may
+ * occur.
+ *
  * @author  Nakul Saraiya
  * @author  Joseph D. Darcy
  * @see     java.lang.Number

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

@@ -122,6 +122,12 @@
  * encoding. For more information on Unicode terminology, refer to the
  * <a href="http://www.unicode.org/glossary/">Unicode Glossary</a>.
  *
+ * <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
+ * class; programmers should treat instances that are
+ * {@linkplain #equals(Object) equal} as interchangeable and should not
+ * use instances for synchronization, or unpredictable behavior may
+ * occur.
+ *
  * @author  Lee Boynton
  * @author  Guy Steele
  * @author  Akira Tanaka

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

@@ -46,6 +46,12 @@
  * constants and methods useful when dealing with a
  * {@code double}.
  *
+ * <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
+ * class; programmers should treat instances that are
+ * {@linkplain #equals(Object) equal} as interchangeable and should not
+ * use instances for synchronization, or unpredictable behavior may
+ * occur.
+ *
  * @author  Lee Boynton
  * @author  Arthur van Hoff
  * @author  Joseph D. Darcy

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

@@ -45,6 +45,12 @@
  * constants and methods useful when dealing with a
  * {@code float}.
  *
+ * <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
+ * class; programmers should treat instances that are
+ * {@linkplain #equals(Object) equal} as interchangeable and should not
+ * use instances for synchronization, or unpredictable behavior may
+ * occur.
+ *
  * @author  Lee Boynton
  * @author  Arthur van Hoff
  * @author  Joseph D. Darcy

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

@@ -50,6 +50,12 @@
  * {@code int}, as well as other constants and methods useful when
  * dealing with an {@code int}.
  *
+ * <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
+ * class; programmers should treat instances that are
+ * {@linkplain #equals(Object) equal} as interchangeable and should not
+ * use instances for synchronization, or unpredictable behavior may
+ * occur.
+ *
  * <p>Implementation note: The implementations of the "bit twiddling"
  * methods (such as {@link #highestOneBit(int) highestOneBit} and
  * {@link #numberOfTrailingZeros(int) numberOfTrailingZeros}) are

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

@@ -50,6 +50,12 @@
  * long}, as well as other constants and methods useful when dealing
  * with a {@code long}.
  *
+ * <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
+ * class; programmers should treat instances that are
+ * {@linkplain #equals(Object) equal} as interchangeable and should not
+ * use instances for synchronization, or unpredictable behavior may
+ * occur.
+ *
  * <p>Implementation note: The implementations of the "bit twiddling"
  * methods (such as {@link #highestOneBit(long) highestOneBit} and
  * {@link #numberOfTrailingZeros(long) numberOfTrailingZeros}) are

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

@@ -81,12 +81,11 @@
  * <p>
  * The {@code ProcessHandle} static factory methods return instances that are
  * <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>,
- * immutable and thread-safe.
- * Use of identity-sensitive operations (including reference equality
- * ({@code ==}), identity hash code, or synchronization) on these instances of
- * {@code ProcessHandle} may have unpredictable results and should be avoided.
- * Use {@link #equals(Object) equals} or
- * {@link #compareTo(ProcessHandle) compareTo} methods to compare ProcessHandles.
+ * immutable and thread-safe. Programmers should treat instances that are
+ * {@linkplain #equals(Object) equal} as interchangeable and should not
+ * use instances for synchronization, or unpredictable behavior may occur.
+ * Use the {@code equals} or {@link #compareTo(ProcessHandle) compareTo} methods
+ * to compare ProcessHandles.
  *
  * @see Process
  * @since 9

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

@@ -941,11 +941,11 @@ public static Version version() {
      *     $VNUM(-$PRE)?
      * </pre></blockquote>
      *
-     * <p>This is a <a href="./doc-files/ValueBased.html">value-based</a>
-     * class; use of identity-sensitive operations (including reference equality
-     * ({@code ==}), identity hash code, or synchronization) on instances of
-     * {@code Version} may have unpredictable results and should be avoided.
-     * </p>
+     * <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
+     * class; programmers should treat instances that are
+     * {@linkplain #equals(Object) equal} as interchangeable and should not
+     * use instances for synchronization, or unpredictable behavior may
+     * occur.</p>
      *
      * @since  9
      */

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

@@ -47,6 +47,12 @@
  * {@code short}, as well as other constants and methods useful when
  * dealing with a {@code short}.
  *
+ * <p>This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
+ * class; programmers should treat instances that are
+ * {@linkplain #equals(Object) equal} as interchangeable and should not
+ * use instances for synchronization, or unpredictable behavior may
+ * occur.
+ *
  * @author  Nakul Saraiya
  * @author  Joseph D. Darcy
  * @see     java.lang.Number