diff --git a/core/src/main/java/org/springframework/security/core/userdetails/User.java b/core/src/main/java/org/springframework/security/core/userdetails/User.java
index dd40ac11b8..6da485958e 100644
--- a/core/src/main/java/org/springframework/security/core/userdetails/User.java
+++ b/core/src/main/java/org/springframework/security/core/userdetails/User.java
@@ -31,7 +31,6 @@ import org.springframework.util.Assert;
 /**
  * Models core user information retrieved by a {@link UserDetailsService}.
  * <p>
- * Implemented with value object semantics (immutable after construction, like a <code>String</code>).
  * Developers may use this class directly, subclass it, or write their own {@link UserDetails} implementation from
  * scratch.
  * <p>
@@ -39,6 +38,11 @@ import org.springframework.util.Assert;
  * intention is that lookups of the same user principal object (in a user registry, for example) will match
  * where the objects represent the same user, not just when all the properties (authorities, password for
  * example) are the same.
+ * <p>
+ * Note that this implementation is not immutable. It implements the {@code CredentialsContainer} interface, in order
+ * to allow the password to be erased after authentication. This may cause side-effects if you are storing instances
+ * in-memory and reusing them. If so, make sure you return a copy from your {@code UserDetailsService} each time it is
+ * invoked.
  *
  * @author Ben Alex
  * @author Luke Taylor
diff --git a/core/src/main/java/org/springframework/security/core/userdetails/UserDetails.java b/core/src/main/java/org/springframework/security/core/userdetails/UserDetails.java
index 689c17d018..6aafd3a1ec 100644
--- a/core/src/main/java/org/springframework/security/core/userdetails/UserDetails.java
+++ b/core/src/main/java/org/springframework/security/core/userdetails/UserDetails.java
@@ -35,16 +35,7 @@ import java.util.Collection;
  * Concrete implementations must take particular care to ensure the non-null
  * contract detailed for each method is enforced. See
  * {@link org.springframework.security.core.userdetails.User} for a
- * reference implementation (which you might like to extend).
- * <p>
- * Concrete implementations should be preferably be immutable &ndash; they should
- * have value object semantics, like a String. The <code>UserDetails</code> may be
- * stored in a cache and multiple threads may use the same instance. Immutable
- * objects are more robust and are guaranteed to be thread-safe. This is not strictly
- * essential (there's nothing within Spring Security itself which absolutely requires it),
- * but if your <tt>UserDetails</tt> object <em>can</em> be modified then it's up to you to make
- * sure that you do so safely and that you manage any caches which may contain copies of
- * the object.
+ * reference implementation (which you might like to extend or use in your code).
  *
  * @see UserDetailsService
  * @see UserCache