diff a/src/java.base/share/classes/java/io/Externalizable.java b/src/java.base/share/classes/java/io/Externalizable.java
--- a/src/java.base/share/classes/java/io/Externalizable.java
+++ b/src/java.base/share/classes/java/io/Externalizable.java
@@ -49,13 +49,19 @@
* ObjectOutputStream.
When an Externalizable object is
* reconstructed, an instance is created using the public no-arg
* constructor, then the readExternal method called. Serializable
* objects are restored by reading them from an ObjectInputStream.
*
- * An Externalizable instance can designate a substitution object via
+ * An Externalizable object can designate a substitution object via
* the writeReplace and readResolve methods documented in the Serializable
- * interface.
+ * interface. To control the serialized form of Records and Externalizable value classes
+ * the record or class uses {@link Serializable} {@code writeReplace}
+ * to delegate to another serializable or externalizable class and that delegate
+ * uses {@code readResolve} to supply the replacement on deserialization.
+ * Value classes implementing {@link Externalizable}
+ * and not using {@code writeReplace} are not supported.
+ *
*
* @see java.io.ObjectOutputStream
* @see java.io.ObjectInputStream
* @see java.io.ObjectOutput
* @see java.io.ObjectInput