Improve javadocs

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/lang/trunk@137869 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/commons/lang/mutable/Mutable.java

@@ -16,26 +16,37 @@
 package org.apache.commons.lang.mutable;
 
 /**
- * A mutable object.
+ * Defines an object that allows mutable access to a value.
+ * <p>
+ * <code>Mutable</code> is used as a generic interface to the implementations
+ * in this package.
+ * <p>
+ * A typical use case would be to enable a primitive or string to be passed
+ * to a method and allow that method to effectively change the value of the
+ * primitive/string. Another use case is to store a frequently changing
+ * primitive in a collection (for example a total in a map) without needing
+ * to create new Integer/Long wrapper objects.
  *
  * @author Matthew Hawthorne
  * @since 2.1
- * @version $Id: Mutable.java,v 1.1 2004/06/11 02:26:32 matth Exp $
+ * @version $Id: Mutable.java,v 1.2 2004/07/05 22:12:22 scolebourne Exp $
  */
 public interface Mutable {
 
     /**
-     * Sets the value of this object.
+     * Gets the value of this mutable.
      *
-     * @param value the value of this object.
+     * @return the stored value
      */
-    public void setValue(Object value);
+    Object getValue();
 
     /**
-     * Gets the value of this object.
+     * Sets the value of this mutable.
      *
-     * @return a value.
+     * @param value  the value to store
+     * @throws NullPointerException if the object is null and null is invalid
+     * @throws ClassCastException if the type is invalid
      */
-    public Object getValue();
+    void setValue(Object value);
 
 }