diff a/src/java.base/share/classes/java/lang/doc-files/ValueBased.html b/src/java.base/share/classes/java/lang/doc-files/ValueBased.html
--- a/src/java.base/share/classes/java/lang/doc-files/ValueBased.html
+++ b/src/java.base/share/classes/java/lang/doc-files/ValueBased.html
@@ -28,45 +28,51 @@
   <title>Value-based Classes</title>
 </head>
 <body>
 <h1 id="ValueBased">{@index "Value-based Classes"}</h1>
 
-Some classes, such as <code>java.lang.Integer</code> and
-<code>java.time.LocalDate</code>, are <em>value-based</em>.
+Some classes, such as {@code java.lang.Integer} and
+{@code java.time.LocalDate}, are <em>value-based</em>.
+The compiler and runtime enforce the value based properties below if it is declared
+as {@code value class} and preview features are enabled.
 A value-based class has the following properties:
 <ul>
     <li>the class declares only final instance fields (though these may contain references
         to mutable objects);</li>
-    <li>the class's implementations of <code>equals</code>, <code>hashCode</code>,
-        and <code>toString</code> compute their results solely from the values
+    <li>the class's implementations of {@code equals}, {@code hashCode},
+        and {@code toString} compute their results solely from the values
         of the class's instance fields (and the members of the objects they
         reference), not from the instance's identity;</li>
     <li>the class's methods treat instances as <em>freely substitutable</em>
-        when equal, meaning that interchanging any two instances <code>x</code> and
-        <code>y</code> that are equal according to <code>equals()</code> produces no
+        when equal, meaning that interchanging any two instances {@code x} and
+        {@code y} that are equal according to {@code equals()} produces no
         visible change in the behavior of the class's methods;</li>
     <li>the class performs no synchronization using an instance's monitor;</li>
-    <li>the class does not declare (or has deprecated any) accessible constructors;</li>
+    <li>the class does not declare (or discourages use of) accessible constructors;</li>
     <li>the class does not provide any instance creation mechanism that promises
         a unique identity on each method call&mdash;in particular, any factory
         method's contract must allow for the possibility that if two independently-produced
-        instances are equal according to <code>equals()</code>, they may also be
-        equal according to <code>==</code>;</li>
-    <li>the class is final, and extends either <code>Object</code> or a hierarchy of
-        abstract classes that declare no instance fields or instance initializers
-        and whose constructors are empty.</li>
+        instances are equal according to {@code equals()}, they may also be
+        equal according to {@code ==};</li>
+    <li>the class is final, and extends either {@code Object} or a hierarchy of
+        abstract value classes.</li>
 </ul>
 
 <p>When two instances of a value-based class are equal (according to `equals`), a program
     should not attempt to distinguish between their identities, whether directly via reference
-    equality or indirectly via an appeal to synchronization, identity hashing,
+    equality {@code ==} or indirectly via an appeal to synchronization, identity hashing,
     serialization, or any other identity-sensitive mechanism.</p>
 
 <p>Synchronization on instances of value-based classes is strongly discouraged,
     because the programmer cannot guarantee exclusive ownership of the
     associated monitor.</p>
 
-<p>Identity-related behavior of value-based classes may change in a future release.
-    For example, synchronization may fail.</p>
+<p>Identity-related behavior of value-based classes may change when implemented as a value class.
+</p>
+<ul>
+    <li>The class may choose to allocate/cache instances differently.
+    <li>The use of the value class for synchronization or with
+    {@linkplain java.lang.ref.Reference object references} result in {@link IdentityException}.
+</ul>
 
 </body>
 </html>
