--- a/jdk/src/java.base/share/classes/java/io/ObjectOutputStream.java	Wed Mar 15 22:57:48 2017 +0000
+++ b/jdk/src/java.base/share/classes/java/io/ObjectOutputStream.java	Wed Mar 15 17:17:16 2017 -0700
@@ -589,22 +589,24 @@
     }
 
     /**
-     * Enable the stream to do replacement of objects in the stream.  When
-     * enabled, the replaceObject method is called for every object being
+     * Enables the stream to do replacement of objects written to the stream.  When
+     * enabled, the {@link #replaceObject} method is called for every object being
      * serialized.
      *
-     * <p>If <code>enable</code> is true, and there is a security manager
-     * installed, this method first calls the security manager's
-     * <code>checkPermission</code> method with a
-     * <code>SerializablePermission("enableSubstitution")</code> permission to
-     * ensure it's ok to enable the stream to do replacement of objects in the
-     * stream.
+     * <p>If object replacement is currently not enabled, and
+     * {@code enable} is true, and there is a security manager installed,
+     * this method first calls the security manager's
+     * {@code checkPermission} method with the
+     * {@code SerializablePermission("enableSubstitution")} permission to
+     * ensure that the caller is permitted to enable the stream to do replacement
+     * of objects written to the stream.
      *
-     * @param   enable boolean parameter to enable replacement of objects
+     * @param   enable true for enabling use of {@code replaceObject} for
+     *          every object being serialized
      * @return  the previous setting before this method was invoked
      * @throws  SecurityException if a security manager exists and its
-     *          <code>checkPermission</code> method denies enabling the stream
-     *          to do replacement of objects in the stream.
+     *          {@code checkPermission} method denies enabling the stream
+     *          to do replacement of objects written to the stream.
      * @see SecurityManager#checkPermission
      * @see java.io.SerializablePermission
      */