- Added javadoc package.html

- Removed all "implements java.io.Serializable" since java.lang.Number already declares it.
- New Javadoc for equals(Object) methods to match Number subclasses, in particular to provide more details for Float and Double.
- equals(Object) methods now use /type/Value() calls instead of ".value" direct references (similar impl to Number subclasses).


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

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

@@ -13,23 +13,21 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package org.apache.commons.lang.mutable;
 
 /**
- * Defines an object that allows mutable access to a value.
+ * Provides mutable access to a value.
  * <p>
- * <code>Mutable</code> is used as a generic interface to the implementations
+ * <code>Mutable</code> is used as a generic interface to the implementations in this package.
- * in this package.
  * <p>
- * A typical use case would be to enable a primitive or string to be passed
+ * A typical use case would be to enable a primitive or string to be passed to a method and allow that method to
- * to a method and allow that method to effectively change the value of the
+ * effectively change the value of the primitive/string. Another use case is to store a frequently changing primitive in
- * primitive/string. Another use case is to store a frequently changing
+ * a collection (for example a total in a map) without needing to create new Integer/Long wrapper objects.
- * 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.2 2004/07/05 22:12:22 scolebourne Exp $
+ * @version $Id: Mutable.java,v 1.3 2004/10/08 19:45:46 ggregory Exp $
  */
 public interface Mutable {
 
@@ -43,9 +41,12 @@ public interface Mutable {
     /**
      * Sets the value of this mutable.
      * 
-     * @param value  the value to store
+     * @param value
-     * @throws NullPointerException if the object is null and null is invalid
+     *            the value to store
-     * @throws ClassCastException if the type is invalid
+     * @throws NullPointerException
+     *             if the object is null and null is invalid
+     * @throws ClassCastException
+     *             if the type is invalid
      */
     void setValue(Object value);
 

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

@@ -13,18 +13,17 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package org.apache.commons.lang.mutable;
 
-import java.io.Serializable;
-
 /**
- * A mutable <code>byte</code>.
+ * A mutable <code>byte</code> wrapper.
  * 
+ * @see Byte
  * @since 2.1
- * @version $Id: MutableByte.java,v 1.5 2004/10/01 17:12:29 ggregory Exp $
+ * @version $Id: MutableByte.java,v 1.6 2004/10/08 19:45:46 ggregory Exp $
  */
-public class MutableByte extends Number
+public class MutableByte extends Number implements Comparable, Mutable {
-        implements Comparable, Mutable, Serializable {
 
     /** Serialization lock. */
     private static final long serialVersionUID = -1585823265L;
@@ -42,7 +41,8 @@ public MutableByte() {
     /**
      * Constructs a new MutableByte with the specified value.
      * 
-     * @param value a value.
+     * @param value
+     *            a value.
      */
     public MutableByte(byte value) {
         super();
@@ -52,8 +52,10 @@ public MutableByte(byte value) {
     /**
      * Constructs a new MutableByte with the specified value.
      * 
-     * @param value a value.
+     * @param value
-     * @throws NullPointerException if the object is null
+     *            a value.
+     * @throws NullPointerException
+     *             if the object is null
      */
     public MutableByte(Number value) {
         super();
@@ -73,7 +75,8 @@ public Object getValue() {
     /**
      * Sets the value.
      * 
-     * @param value  the value to set
+     * @param value
+     *            the value to set
      */
     public void setValue(byte value) {
         this.value = value;
@@ -82,9 +85,12 @@ public void setValue(byte value) {
     /**
      * Sets the value from any Number instance.
      * 
-     * @param value  the value to set
+     * @param value
-     * @throws NullPointerException if the object is null
+     *            the value to set
-     * @throws ClassCastException if the type is invalid
+     * @throws NullPointerException
+     *             if the object is null
+     * @throws ClassCastException
+     *             if the type is not a {@link Number}
      */
     public void setValue(Object value) {
         setValue(((Number) value).byteValue());
@@ -113,16 +119,17 @@ public double doubleValue() {
 
     //-----------------------------------------------------------------------
     /**
-     * Checks if this object equals the specified object.
+     * Compares this object against the specified object. The result is <code>true</code> if and only if the argument
-     * <p>
+     * is not <code>null</code> and is a <code>MutableByte</code> object that contains the same <code>byte</code>
-     * The object must be a MutableByte with the same value to be equal.
+     * value as this object.
      * 
-     * @param obj  the object to compare to
+     * @param obj
-     * @return true if equal
+     *            the object to compare with.
+     * @return <code>true</code> if the objects are the same; <code>false</code> otherwise.
      */
     public boolean equals(Object obj) {
         if (obj instanceof MutableByte) {
-            return (value == ((MutableByte) obj).value);
+            return value == ((MutableByte) obj).byteValue();
         }
         return false;
     }
@@ -139,8 +146,10 @@ public int hashCode() {
     /**
      * Compares this mutable to another in ascending order.
      * 
-     * @param obj  the mutable to compare to
+     * @param obj
+     *            the mutable to compare to
      * @return negative if this is less, zero if equal, positive if greater
+     * @throws ClassCastException if the argument is not a MutableByte
      */
     public int compareTo(Object obj) {
         MutableByte other = (MutableByte) obj;

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

@@ -13,20 +13,19 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.apache.commons.lang.mutable;
 
-import java.io.Serializable;
+package org.apache.commons.lang.mutable;
 
 import org.apache.commons.lang.math.NumberUtils;
 
 /**
- * A mutable <code>double</code>.
+ * A mutable <code>double</code> wrapper.
  * 
+ * @see Double
  * @since 2.1
- * @version $Id: MutableDouble.java,v 1.4 2004/07/07 23:50:28 scolebourne Exp $
+ * @version $Id: MutableDouble.java,v 1.5 2004/10/08 19:45:46 ggregory Exp $
  */
-public class MutableDouble extends Number
+public class MutableDouble extends Number implements Comparable, Mutable {
-        implements Comparable, Mutable, Serializable {
 
     /** Serialization lock. */
     private static final long serialVersionUID = 1587163916L;
@@ -44,7 +43,8 @@ public MutableDouble() {
     /**
      * Constructs a new MutableDouble with the specified value.
      * 
-     * @param value a value.
+     * @param value
+     *            a value.
      */
     public MutableDouble(double value) {
         super();
@@ -54,8 +54,10 @@ public MutableDouble(double value) {
     /**
      * Constructs a new MutableDouble with the specified value.
      * 
-     * @param value a value.
+     * @param value
-     * @throws NullPointerException if the object is null
+     *            a value.
+     * @throws NullPointerException
+     *             if the object is null
      */
     public MutableDouble(Number value) {
         super();
@@ -75,7 +77,8 @@ public Object getValue() {
     /**
      * Sets the value.
      * 
-     * @param value  the value to set
+     * @param value
+     *            the value to set
      */
     public void setValue(double value) {
         this.value = value;
@@ -84,9 +87,12 @@ public void setValue(double value) {
     /**
      * Sets the value from any Number instance.
      * 
-     * @param value  the value to set
+     * @param value
-     * @throws NullPointerException if the object is null
+     *            the value to set
-     * @throws ClassCastException if the type is invalid
+     * @throws NullPointerException
+     *             if the object is null
+     * @throws ClassCastException
+     *             if the type is not a {@link Number}
      */
     public void setValue(Object value) {
         setValue(((Number) value).doubleValue());
@@ -129,19 +135,38 @@ public boolean isInfinite() {
 
     //-----------------------------------------------------------------------
     /**
-     * Checks if this object equals the specified object.
+     * Compares this object against the specified object. The result is <code>true</code> if and only if the argument
+     * is not <code>null</code> and is a <code>Double</code> object that represents a double that has the identical
+     * bit pattern to the bit pattern of the double represented by this object. For this purpose, two
+     * <code>double</code> values are considered to be the same if and only if the method
+     * {@link Double#doubleToLongBits(double)}returns the same long value when applied to each.
      * <p>
-     * The object must be a MutableDouble with the same value to be equal.
+     * Note that in most cases, for two instances of class <code>Double</code>,<code>d1</code> and <code>d2</code>,
+     * the value of <code>d1.equals(d2)</code> is <code>true</code> if and only if <blockquote>
      * 
-     * @param obj  the object to compare to
+     * <pre>
-     * @return true if equal
+     *   d1.doubleValue()&nbsp;== d2.doubleValue()
+     * </pre>
+     * 
+     * </blockquote>
+     * <p>
+     * also has the value <code>true</code>. However, there are two exceptions:
+     * <ul>
+     * <li>If <code>d1</code> and <code>d2</code> both represent <code>Double.NaN</code>, then the
+     * <code>equals</code> method returns <code>true</code>, even though <code>Double.NaN==Double.NaN</code> has
+     * the value <code>false</code>.
+     * <li>If <code>d1</code> represents <code>+0.0</code> while <code>d2</code> represents <code>-0.0</code>,
+     * or vice versa, the <code>equal</code> test has the value <code>false</code>, even though
+     * <code>+0.0==-0.0</code> has the value <code>true</code>. This allows hashtables to operate properly.
+     * </ul>
+     * 
+     * @param obj
+     *            the object to compare with.
+     * @return <code>true</code> if the objects are the same; <code>false</code> otherwise.
      */
     public boolean equals(Object obj) {
-        if (obj instanceof MutableDouble) {
+        return (obj instanceof MutableDouble)
-            double other = ((MutableDouble) obj).value;
+            && (Double.doubleToLongBits(((MutableDouble) obj).value) == Double.doubleToLongBits(value));
-            return (Double.doubleToLongBits(other) == Double.doubleToLongBits(value));
-        }
-        return false;
     }
 
     /**
@@ -157,8 +182,10 @@ public int hashCode() {
     /**
      * Compares this mutable to another in ascending order.
      * 
-     * @param obj  the mutable to compare to
+     * @param obj
+     *            the mutable to compare to
      * @return negative if this is less, zero if equal, positive if greater
+     * @throws ClassCastException if the argument is not a MutableDouble
      */
     public int compareTo(Object obj) {
         MutableDouble other = (MutableDouble) obj;

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

@@ -13,20 +13,19 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.apache.commons.lang.mutable;
 
-import java.io.Serializable;
+package org.apache.commons.lang.mutable;
 
 import org.apache.commons.lang.math.NumberUtils;
 
 /**
- * A mutable <code>float</code>.
+ * A mutable <code>float</code> wrapper.
  * 
+ * @see Float
  * @since 2.1
- * @version $Id: MutableFloat.java,v 1.5 2004/10/01 17:12:29 ggregory Exp $
+ * @version $Id: MutableFloat.java,v 1.6 2004/10/08 19:45:46 ggregory Exp $
  */
-public class MutableFloat extends Number
+public class MutableFloat extends Number implements Comparable, Mutable {
-        implements Comparable, Mutable, Serializable {
 
     /** Serialization lock. */
     private static final long serialVersionUID = 5787169186L;
@@ -44,7 +43,8 @@ public MutableFloat() {
     /**
      * Constructs a new MutableFloat with the specified value.
      * 
-     * @param value a value.
+     * @param value
+     *            a value.
      */
     public MutableFloat(float value) {
         super();
@@ -54,8 +54,10 @@ public MutableFloat(float value) {
     /**
      * Constructs a new MutableFloat with the specified value.
      * 
-     * @param value a value.
+     * @param value
-     * @throws NullPointerException if the object is null
+     *            a value.
+     * @throws NullPointerException
+     *             if the object is null
      */
     public MutableFloat(Number value) {
         super();
@@ -75,7 +77,8 @@ public Object getValue() {
     /**
      * Sets the value.
      * 
-     * @param value  the value to set
+     * @param value
+     *            the value to set
      */
     public void setValue(float value) {
         this.value = value;
@@ -84,9 +87,12 @@ public void setValue(float value) {
     /**
      * Sets the value from any Number instance.
      * 
-     * @param value  the value to set
+     * @param value
-     * @throws NullPointerException if the object is null
+     *            the value to set
-     * @throws ClassCastException if the type is invalid
+     * @throws NullPointerException
+     *             if the object is null
+     * @throws ClassCastException
+     *             if the type is not a {@link Number}
      */
     public void setValue(Object value) {
         setValue(((Number) value).floatValue());
@@ -127,23 +133,61 @@ public boolean isInfinite() {
         return Float.isInfinite(value);
     }
 
+    /**
+     * Compares this object against some other object. The result is <code>true</code> if and only if the argument is
+     * not <code>null</code> and is a <code>Float</code> object that represents a <code>float</code> that has the
+     * identical bit pattern to the bit pattern of the <code>float</code> represented by this object. For this
+     * purpose, two float values are considered to be the same if and only if the method
+     * {@link Float#floatToIntBits(float)}returns the same int value when applied to each.
+     * <p>
+     * Note that in most cases, for two instances of class <code>Float</code>,<code>f1</code> and <code>f2</code>,
+     * the value of <code>f1.equals(f2)</code> is <code>true</code> if and only if <blockquote>
+     * 
+     * <pre>
+     *   f1.floatValue() == f2.floatValue()
+     * </pre>
+     * 
+     * </blockquote>
+     * <p>
+     * also has the value <code>true</code>. However, there are two exceptions:
+     * <ul>
+     * <li>If <code>f1</code> and <code>f2</code> both represent <code>Float.NaN</code>, then the
+     * <code>equals</code> method returns <code>true</code>, even though <code>Float.NaN==Float.NaN</code> has
+     * the value <code>false</code>.
+     * <li>If <code>f1</code> represents <code>+0.0f</code> while <code>f2</code> represents <code>-0.0f</code>,
+     * or vice versa, the <code>equal</code> test has the value <code>false</code>, even though
+     * <code>0.0f==-0.0f</code> has the value <code>true</code>.
+     * </ul>
+     * This definition allows hashtables to operate properly.
+     * 
+     * @param obj
+     *            the object to be compared
+     * @return <code>true</code> if the objects are the same; <code>false</code> otherwise.
+     * @throws ClassCastException if the argument is not a MutableFloat
+     * @see java.lang.Float#floatToIntBits(float)
+     */
+    public boolean equals(Object obj) {
+        return (obj instanceof MutableFloat)
+            && (Float.floatToIntBits(((MutableFloat) obj).value) == Float.floatToIntBits(value));
+    }
+
     //-----------------------------------------------------------------------
     /**
      * Checks if this object equals the specified object.
      * <p>
      * The object must be a MutableFloat with the same value to be equal.
      * 
-     * @param obj  the object to compare to
+     * @param obj
+     *            the object to compare to
      * @return true if equal
      */
-    public boolean equals(Object obj) {
+    //    public boolean equals(Object obj) {
-        if (obj instanceof MutableFloat) {
+    //        if (obj instanceof MutableFloat) {
-            float other = ((MutableFloat) obj).value;
+    //            float other = ((MutableFloat) obj).value;
-            return (Float.floatToIntBits(other) == Float.floatToIntBits(value));
+    //            return (Float.floatToIntBits(other) == Float.floatToIntBits(value));
-        }
+    //        }
-        return false;
+    //        return false;
-    }
+    //    }
-
     /**
      * Returns a suitable hashcode for this mutable.
      * 
@@ -156,7 +200,8 @@ public int hashCode() {
     /**
      * Compares this mutable to another in ascending order.
      * 
-     * @param obj  the mutable to compare to
+     * @param obj
+     *            the mutable to compare to
      * @return negative if this is less, zero if equal, positive if greater
      */
     public int compareTo(Object obj) {

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

@@ -13,18 +13,17 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package org.apache.commons.lang.mutable;
 
-import java.io.Serializable;
-
 /**
- * A mutable <code>int</code>.
+ * A mutable <code>int</code> wrapper.
  * 
+ * @see Integer
  * @since 2.1
- * @version $Id: MutableInt.java,v 1.3 2004/10/01 17:12:29 ggregory Exp $
+ * @version $Id: MutableInt.java,v 1.4 2004/10/08 19:45:46 ggregory Exp $
  */
-public class MutableInt extends Number
+public class MutableInt extends Number implements Comparable, Mutable {
-        implements Comparable, Mutable, Serializable {
 
     /** Serialization lock. */
     private static final long serialVersionUID = 512176391864L;
@@ -42,7 +41,8 @@ public MutableInt() {
     /**
      * Constructs a new MutableInt with the specified value.
      * 
-     * @param value a value.
+     * @param value
+     *                  a value.
      */
     public MutableInt(int value) {
         super();
@@ -52,8 +52,10 @@ public MutableInt(int value) {
     /**
      * Constructs a new MutableInt with the specified value.
      * 
-     * @param value a value.
+     * @param value
-     * @throws NullPointerException if the object is null
+     *                  a value.
+     * @throws NullPointerException
+     *                  if the object is null
      */
     public MutableInt(Number value) {
         super();
@@ -73,7 +75,8 @@ public Object getValue() {
     /**
      * Sets the value.
      * 
-     * @param value  the value to set
+     * @param value
+     *                  the value to set
      */
     public void setValue(int value) {
         this.value = value;
@@ -82,9 +85,12 @@ public void setValue(int value) {
     /**
      * Sets the value from any Number instance.
      * 
-     * @param value  the value to set
+     * @param value
-     * @throws NullPointerException if the object is null
+     *                  the value to set
-     * @throws ClassCastException if the type is invalid
+     * @throws NullPointerException
+     *                  if the object is null
+     * @throws ClassCastException
+     *                  if the type is not a {@link Number}
      */
     public void setValue(Object value) {
         setValue(((Number) value).intValue());
@@ -109,16 +115,17 @@ public double doubleValue() {
 
     //-----------------------------------------------------------------------
     /**
-     * Checks if this object equals the specified object.
+     * Compares this object to the specified object. The result is <code>true</code> if and only if the argument is
-     * <p>
+     * not <code>null</code> and is an <code>MutableInt</code> object that contains the same <code>int</code> value
-     * The object must be a MutableInt with the same value to be equal.
+     * as this object.
      * 
-     * @param obj  the object to compare to
+     * @param obj
-     * @return true if equal
+     *                  the object to compare with.
+     * @return <code>true</code> if the objects are the same; <code>false</code> otherwise.
      */
     public boolean equals(Object obj) {
         if (obj instanceof MutableInt) {
-            return (value == ((MutableInt) obj).value);
+            return (value == ((MutableInt) obj).intValue());
         }
         return false;
     }
@@ -135,8 +142,10 @@ public int hashCode() {
     /**
      * Compares this mutable to another in ascending order.
      * 
-     * @param obj  the mutable to compare to
+     * @param obj
+     *                  the mutable to compare to
      * @return negative if this is less, zero if equal, positive if greater
+     * @throws ClassCastException if the argument is not a MutableInt
      */
     public int compareTo(Object obj) {
         MutableInt other = (MutableInt) obj;

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

@@ -13,18 +13,17 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package org.apache.commons.lang.mutable;
 
-import java.io.Serializable;
-
 /**
- * A mutable <code>long</code>.
+ * A mutable <code>long</code> wrapper.
  * 
+ * @see Long
  * @since 2.1
- * @version $Id: MutableLong.java,v 1.5 2004/10/01 17:12:29 ggregory Exp $
+ * @version $Id: MutableLong.java,v 1.6 2004/10/08 19:45:46 ggregory Exp $
  */
-public class MutableLong extends Number
+public class MutableLong extends Number implements Comparable, Mutable {
-        implements Comparable, Mutable, Serializable {
 
     /** Serialization lock. */
     private static final long serialVersionUID = 62986528375L;
@@ -42,7 +41,8 @@ public MutableLong() {
     /**
      * Constructs a new MutableLong with the specified value.
      * 
-     * @param value a value.
+     * @param value
+     *            a value.
      */
     public MutableLong(long value) {
         super();
@@ -52,8 +52,10 @@ public MutableLong(long value) {
     /**
      * Constructs a new MutableLong with the specified value.
      * 
-     * @param value a value.
+     * @param value
-     * @throws NullPointerException if the object is null
+     *            a value.
+     * @throws NullPointerException
+     *             if the object is null
      */
     public MutableLong(Number value) {
         super();
@@ -73,7 +75,8 @@ public Object getValue() {
     /**
      * Sets the value.
      * 
-     * @param value  the value to set
+     * @param value
+     *            the value to set
      */
     public void setValue(long value) {
         this.value = value;
@@ -82,9 +85,12 @@ public void setValue(long value) {
     /**
      * Sets the value from any Number instance.
      * 
-     * @param value  the value to set
+     * @param value
-     * @throws NullPointerException if the object is null
+     *            the value to set
-     * @throws ClassCastException if the type is invalid
+     * @throws NullPointerException
+     *             if the object is null
+     * @throws ClassCastException
+     *             if the type is not a {@link Number}
      */
     public void setValue(Object value) {
         setValue(((Number) value).longValue());
@@ -109,16 +115,17 @@ public double doubleValue() {
 
     //-----------------------------------------------------------------------
     /**
-     * Checks if this object equals the specified object.
+     * Compares this object against the specified object. The result is <code>true</code> if and only if the argument
-     * <p>
+     * is not <code>null</code> and is a <code>MutableLong</code> object that contains the same <code>long</code>
-     * The object must be a MutableLong with the same value to be equal.
+     * value as this object.
      * 
-     * @param obj  the object to compare to
+     * @param obj
-     * @return true if equal
+     *            the object to compare with.
+     * @return <code>true</code> if the objects are the same; <code>false</code> otherwise.
      */
     public boolean equals(Object obj) {
         if (obj instanceof MutableLong) {
-            return (value == ((MutableLong) obj).value);
+            return value == ((MutableLong) obj).longValue();
         }
         return false;
     }
@@ -135,8 +142,10 @@ public int hashCode() {
     /**
      * Compares this mutable to another in ascending order.
      * 
-     * @param obj  the mutable to compare to
+     * @param obj
+     *            the mutable to compare to
      * @return negative if this is less, zero if equal, positive if greater
+     * @throws ClassCastException if the argument is not a MutableLong
      */
     public int compareTo(Object obj) {
         MutableLong other = (MutableLong) obj;

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

@@ -13,18 +13,18 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package org.apache.commons.lang.mutable;
 
 import java.io.Serializable;
 
 /**
- * A mutable <code>Object</code>.
+ * A mutable <code>Object</code> wrapper.
  * 
  * @since 2.1
- * @version $Id: MutableObject.java,v 1.2 2004/09/01 17:42:56 ggregory Exp $
+ * @version $Id: MutableObject.java,v 1.3 2004/10/08 19:45:46 ggregory Exp $
  */
-public class MutableObject
+public class MutableObject implements Mutable, Serializable {
-        implements Mutable, Serializable {
 
     /** Serialization lock. */
     private static final long serialVersionUID = 86241875189L;
@@ -42,7 +42,8 @@ public MutableObject() {
     /**
      * Constructs a new MutableObject with the specified value.
      * 
-     * @param value a value.
+     * @param value
+     *            a value.
      */
     public MutableObject(Object value) {
         super();
@@ -62,7 +63,8 @@ public Object getValue() {
     /**
      * Sets the value.
      * 
-     * @param value  the value to set
+     * @param value
+     *            the value to set
      */
     public void setValue(Object value) {
         this.value = value;
@@ -70,12 +72,14 @@ public void setValue(Object value) {
 
     //-----------------------------------------------------------------------
     /**
-     * Checks if this object equals the specified object.
+     * Compares this object against the specified object. The result is <code>true</code> if and only if the argument
-     * <p>
+     * is not <code>null</code> and is a <code>MutableObject</code> object that contains the same <code>Object</code>
-     * The object must be a MutableObject with an equal value to be equal.
+     * value as this object.
      * 
-     * @param obj  the object to compare to
+     * @param obj
-     * @return true if equal
+     *            the object to compare with.
+     * @return <code>true</code> if the objects are the same; <code>false</code> otherwise.
+     * @throws ClassCastException if the argument is not a MutableObject
      */
     public boolean equals(Object obj) {
         if (obj instanceof MutableObject) {

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

@@ -13,18 +13,17 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package org.apache.commons.lang.mutable;
 
-import java.io.Serializable;
-
 /**
- * A mutable <code>short</code>.
+ * A mutable <code>short</code> wrapper.
  * 
+ * @see Short
  * @since 2.1
- * @version $Id: MutableShort.java,v 1.5 2004/10/01 17:12:29 ggregory Exp $
+ * @version $Id: MutableShort.java,v 1.6 2004/10/08 19:45:46 ggregory Exp $
  */
-public class MutableShort extends Number
+public class MutableShort extends Number implements Comparable, Mutable {
-        implements Comparable, Mutable, Serializable {
 
     /** Serialization lock. */
     private static final long serialVersionUID = -2135791679L;
@@ -42,7 +41,8 @@ public MutableShort() {
     /**
      * Constructs a new MutableShort with the specified value.
      * 
-     * @param value a value.
+     * @param value
+     *                  a value.
      */
     public MutableShort(short value) {
         super();
@@ -52,8 +52,10 @@ public MutableShort(short value) {
     /**
      * Constructs a new MutableShort with the specified value.
      * 
-     * @param value a value.
+     * @param value
-     * @throws NullPointerException if the object is null
+     *                  a value.
+     * @throws NullPointerException
+     *                  if the object is null
      */
     public MutableShort(Number value) {
         super();
@@ -73,7 +75,8 @@ public Object getValue() {
     /**
      * Sets the value.
      * 
-     * @param value  the value to set
+     * @param value
+     *                  the value to set
      */
     public void setValue(short value) {
         this.value = value;
@@ -82,9 +85,12 @@ public void setValue(short value) {
     /**
      * Sets the value from any Number instance.
      * 
-     * @param value  the value to set
+     * @param value
-     * @throws NullPointerException if the object is null
+     *                  the value to set
-     * @throws ClassCastException if the type is invalid
+     * @throws NullPointerException
+     *                  if the object is null
+     * @throws ClassCastException
+     *                  if the type is not a {@link Number}
      */
     public void setValue(Object value) {
         setValue(((Number) value).shortValue());
@@ -113,16 +119,17 @@ public double doubleValue() {
 
     //-----------------------------------------------------------------------
     /**
-     * Checks if this object equals the specified object.
+     * Compares this object against the specified object. The result is <code>true</code> if and only if the argument
-     * <p>
+     * is not <code>null</code> and is a <code>MutableShort</code> object that contains the same <code>short</code>
-     * The object must be a MutableShort with the same value to be equal.
+     * value as this object.
      * 
-     * @param obj  the object to compare to
+     * @param obj
-     * @return true if equal
+     *                  the object to compare with.
+     * @return <code>true</code> if the objects are the same; <code>false</code> otherwise.
      */
     public boolean equals(Object obj) {
         if (obj instanceof MutableShort) {
-            return (value == ((MutableShort) obj).value);
+            return (value == ((MutableShort) obj).shortValue());
         }
         return false;
     }
@@ -139,8 +146,10 @@ public int hashCode() {
     /**
      * Compares this mutable to another in ascending order.
      * 
-     * @param obj  the mutable to compare to
+     * @param obj
+     *                  the mutable to compare to
      * @return negative if this is less, zero if equal, positive if greater
+     * @throws ClassCastException if the argument is not a MutableShort
      */
     public int compareTo(Object obj) {
         MutableShort other = (MutableShort) obj;

src/java/org/apache/commons/lang/mutable/package.html

@@ -0,0 +1,39 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<!--
+
+Copyright 2002-2004 The Apache Software Foundation.
+
+ 
+
+Licensed under the Apache License, Version 2.0 (the "License");
+
+you may not use this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+
+
+Unless required by applicable law or agreed to in writing, software
+
+distributed under the License is distributed on an "AS IS" BASIS,
+
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+See the License for the specific language governing permissions and
+
+limitations under the License.
+
+-->
+  <title></title>
+</head>
+<body>
+Provides typed mutable wrappers to primitive values and Object.
+@since 2.1
+</body>
+</html>