SEC-1170: Some updates to UserDetails-related Javadoc.

core/src/main/java/org/springframework/security/core/userdetails/UserCache.java

@@ -23,7 +23,7 @@ package org.springframework.security.core.userdetails;
  * Implementations should provide appropriate methods to set their cache parameters (e.g. time-to-live) and/or force
  * removal of entities before their normal expiration. These are not part of the <code>UserCache</code>
  * interface contract because they vary depending on the type of caching
- * system used (e.g. in-memory vs disk vs cluster vs hybrid).
+ * system used (in-memory, disk, cluster, hybrid etc.).
  * <p>
  * Caching is generally only required in applications which do not maintain server-side state, such as remote clients
  * or web services. The authentication credentials are then presented on each invocation and the overhead of accessing

core/src/main/java/org/springframework/security/core/userdetails/UserDetails.java

@@ -31,20 +31,23 @@ import java.util.List;
  * into {@link Authentication} objects. This allows non-security related user
  * information (such as email addresses, telephone numbers etc) to be stored
  * in a convenient location.
- * </p>
- *
  * <p>
  * 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>
- *
  * <p>
- * Concrete implementations should be immutable (value object semantics,
- * like a String). This is because the <code>UserDetails</code> will be
- * stored in caches and as such multiple threads may use the same instance.
- * </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.
+ *
+ * @see UserDetailsService
+ * @see UserCache
  *
  * @author Ben Alex
  * @version $Id$

core/src/main/java/org/springframework/security/core/userdetails/UserDetailsService.java

@@ -27,7 +27,6 @@ import org.springframework.dao.DataAccessException;
  * <p>
  * The interface requires only one read-only method, which simplifies support
  * of new data access strategies.
- * </p>
  *
  * @author Ben Alex
  * @version $Id$
@@ -37,7 +36,7 @@ public interface UserDetailsService {
 
     /**
      * Locates the user based on the username. In the actual implementation, the search may possibly be case
-     * insensitive, or case insensitive depending on how the implementaion instance is configured. In this case, the
+     * insensitive, or case insensitive depending on how the implementation instance is configured. In this case, the
      * <code>UserDetails</code> object that comes back may have a username that is of a different case than what was
      * actually requested..
      *