harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r770909 [4/10] - in /harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang: ./ ref/ reflect/
Date Sat, 02 May 2009 08:09:57 GMT
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/IllegalThreadStateException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/IllegalThreadStateException.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/IllegalThreadStateException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/IllegalThreadStateException.java Sat May  2 08:09:50 2009
@@ -17,30 +17,30 @@
 
 package java.lang;
 
-
 /**
- * This runtime exception is thrown when an operation is attempted which is not
- * possible given the state that the executing thread is in.
+ * Thrown when an operation is attempted which is not possible given the state
+ * that the executing thread is in.
  */
 public class IllegalThreadStateException extends IllegalArgumentException {
 
     private static final long serialVersionUID = -7626246362397460174L;
 
     /**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
-	public IllegalThreadStateException() {
-		super();
-	}
+     * Constructs a new {@code IllegalThreadStateException} that includes the
+     * current stack trace.
+     */
+    public IllegalThreadStateException() {
+        super();
+    }
 
-	/**
-	 * Constructs a new instance of this class with its walkback and message
-	 * filled in.
-	 * 
-	 * @param detailMessage
-	 *            String The detail message for the exception.
-	 */
-	public IllegalThreadStateException(String detailMessage) {
-		super(detailMessage);
-	}
+    /**
+     * Constructs a new {@code IllegalThreadStateException} with the current
+     * stack trace and the specified detail message.
+     * 
+     * @param detailMessage
+     *            the detail message for this exception.
+     */
+    public IllegalThreadStateException(String detailMessage) {
+        super(detailMessage);
+    }
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/IncompatibleClassChangeError.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/IncompatibleClassChangeError.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/IncompatibleClassChangeError.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/IncompatibleClassChangeError.java Sat May  2 08:09:50 2009
@@ -19,8 +19,9 @@
 
 
 /**
- * This class is the superclass of all classes which represent errors which
- * occur when inconsistant class files are loaded into the same running image.
+ * {@code IncompatibleClassChangeError} is the superclass of all classes which
+ * represent errors that occur when inconsistent class files are loaded into
+ * the same running image.
  * 
  * @see Error
  */
@@ -29,20 +30,21 @@
     private static final long serialVersionUID = -4914975503642802119L;
 
     /**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
-	public IncompatibleClassChangeError() {
-		super();
-	}
+     * Constructs a new {@code IncompatibleClassChangeError} that includes the
+     * current stack trace.
+     */
+    public IncompatibleClassChangeError() {
+        super();
+    }
 
-	/**
-	 * Constructs a new instance of this class with its walkback and message
-	 * filled in.
-	 * 
-	 * @param detailMessage
-	 *            String The detail message for the exception.
-	 */
-	public IncompatibleClassChangeError(String detailMessage) {
-		super(detailMessage);
-	}
+    /**
+     * Constructs a new {@code IncompatibleClassChangeError} with the current
+     * stack trace and the specified detail message.
+     * 
+     * @param detailMessage
+     *            the detail message for this error.
+     */
+    public IncompatibleClassChangeError(String detailMessage) {
+        super(detailMessage);
+    }
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/IndexOutOfBoundsException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/IndexOutOfBoundsException.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/IndexOutOfBoundsException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/IndexOutOfBoundsException.java Sat May  2 08:09:50 2009
@@ -17,31 +17,30 @@
 
 package java.lang;
 
-
 /**
- * This runtime exception is thrown when a program attempts to access a value in
- * an indexable collection using a value which is outside the possible range of
- * indices.
+ * Thrown when a program attempts to access a value in an indexable collection
+ * using a value which is outside of the range of valid indices.
  */
 public class IndexOutOfBoundsException extends RuntimeException {
 
     private static final long serialVersionUID = 234122996006267687L;
 
     /**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
-	public IndexOutOfBoundsException() {
-		super();
-	}
+     * Constructs a new {@code IndexOutOfBoundsException} that includes the
+     * current stack trace.
+     */
+    public IndexOutOfBoundsException() {
+        super();
+    }
 
-	/**
-	 * Constructs a new instance of this class with its walkback and message
-	 * filled in.
-	 * 
-	 * @param detailMessage
-	 *            String The detail message for the exception.
-	 */
-	public IndexOutOfBoundsException(String detailMessage) {
-		super(detailMessage);
-	}
+    /**
+     * Constructs a new {@code IndexOutOfBoundsException} with the current stack
+     * trace and the specified detail message.
+     * 
+     * @param detailMessage
+     *            the detail message for this exception.
+     */
+    public IndexOutOfBoundsException(String detailMessage) {
+        super(detailMessage);
+    }
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InheritableThreadLocal.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InheritableThreadLocal.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InheritableThreadLocal.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InheritableThreadLocal.java Sat May  2 08:09:50 2009
@@ -19,26 +19,33 @@
 
 
 /**
- * An InheritableThreadLocal is very similar to a ThreadLocal, with the added
- * functionality that a child Thread inherits all InheritableThreadLocal from
- * its parent Thread upon Thread creation time.
+ * A thread-local variable whose value is passed from parent to child thread. By
+ * default, the value of an inheritable thread-local variable of a child thread
+ * is initialized with the value of the parent thread's variable at thread
+ * creation time. However, subclasses may override {code #childValue(Object)}
+ * to provide an arbitrary function for passing the value of a parent's
+ * thread-local variable to the child's thread-local variable.
  * 
  * @see java.lang.Thread
  * @see java.lang.ThreadLocal
  */
-
 public class InheritableThreadLocal<T> extends ThreadLocal<T> {
 	/**
-	 * Constructs a new InheritableThreadLocal object
+     * Creates a new inheritable thread-local variable.
 	 */
 	public InheritableThreadLocal() {
 		super();
 	}
 
 	/**
-	 * Computes the created Thread's initial value for this
-	 * InheritableThreadLocal based on the current value of the same local on
-	 * the creator Thread.
+     * Computes the initial value of this thread-local variable for the child
+     * thread given the parent thread's value. Called from the parent thread
+     * when creating a child thread. The default implementation returns the
+     * parent thread's value.
+     *
+     * @param parentValue
+     *            the value of the variable in the parent thread.
+     * @return the initial value of the variable for the child thread.
 	 */
 	protected T childValue(T parentValue) {
 		return parentValue;

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InstantiationError.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InstantiationError.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InstantiationError.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InstantiationError.java Sat May  2 08:09:50 2009
@@ -17,46 +17,44 @@
 
 package java.lang;
 
-
 /**
- * This error is thrown when the VM notices that a an attempt is being made to
- * create a new instance of a class which has no visible constructors from the
- * location where new is invoked.
+ * Thrown when the virtual machine notices that a program tries to create a new
+ * instance of a class which has no visible constructors from the location where
+ * {@code new} is invoked.
  * <p>
  * Note that this can only occur when inconsistent class files are being loaded.
- * 
  */
 public class InstantiationError extends IncompatibleClassChangeError {
-	private static final long serialVersionUID = -4885810657349421204L;
+    private static final long serialVersionUID = -4885810657349421204L;
 
-	/**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 * 
-	 */
-	public InstantiationError() {
-		super();
-	}
-
-	/**
-	 * Constructs a new instance of this class with its walkback and message
-	 * filled in.
-	 * 
-	 * @param detailMessage
-	 *            String The detail message for the exception.
-	 */
-	public InstantiationError(String detailMessage) {
-		super(detailMessage);
-	}
-
-	/**
-	 * Constructs a new instance of this class with its walkback and message
-	 * filled in.
-	 * 
-	 * @param clazz
-	 *            Class The class which cannot be instantiated.
-	 */
-	InstantiationError(Class<?> clazz) {
-		super(clazz.getName());
-	}
+    /**
+     * Constructs a new {@code InstantiationError} that includes the current
+     * stack trace.
+     */
+    public InstantiationError() {
+        super();
+    }
+
+    /**
+     * Constructs a new {@code InstantiationError} with the current stack trace
+     * and the specified detail message.
+     * 
+     * @param detailMessage
+     *            the detail message for this error.
+     */
+    public InstantiationError(String detailMessage) {
+        super(detailMessage);
+    }
+
+    /**
+     * Constructs a new {@code InstantiationError} with the current stack trace
+     * and the class that caused this error.
+     * 
+     * @param clazz
+     *            the class that can not be instantiated.
+     */
+    InstantiationError(Class<?> clazz) {
+        super(clazz.getName());
+    }
 
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InstantiationException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InstantiationException.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InstantiationException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InstantiationException.java Sat May  2 08:09:50 2009
@@ -17,42 +17,40 @@
 
 package java.lang;
 
-
 /**
- * This exception is thrown when a program attempts to access a constructor
- * which is not accessible from the location where the reference is made.
- * 
+ * Thrown when a program attempts to access a constructor which is not
+ * accessible from the location where the reference is made.
  */
 public class InstantiationException extends Exception {
-	private static final long serialVersionUID = -8441929162975509110L;
-
-	/**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 * 
-	 */
-	public InstantiationException() {
-		super();
-	}
-
-	/**
-	 * Constructs a new instance of this class with its walkback and message
-	 * filled in.
-	 * 
-	 * @param detailMessage
-	 *            String The detail message for the exception.
-	 */
-	public InstantiationException(String detailMessage) {
-		super(detailMessage);
-	}
+    private static final long serialVersionUID = -8441929162975509110L;
 
-	/**
-	 * Constructs a new instance of this class with its walkback and message
-	 * filled in.
-	 * 
-	 * @param clazz
-	 *            Class The class which cannot be instantiated.
-	 */
-	InstantiationException(Class<?> clazz) {
-		super(clazz.getName());
-	}
+    /**
+     * Constructs a new {@code InstantiationException} that includes the current
+     * stack trace.
+     */
+    public InstantiationException() {
+        super();
+    }
+
+    /**
+     * Constructs a new {@code InstantiationException} with the current stack
+     * trace and the specified detail message.
+     * 
+     * @param detailMessage
+     *            the detail message for this exception.
+     */
+    public InstantiationException(String detailMessage) {
+        super(detailMessage);
+    }
+
+    /**
+     * Constructs a new {@code InstantiationException} with the current stack
+     * trace and the class that caused this exception.
+     * 
+     * @param clazz
+     *            the class that can not be instantiated.
+     */
+    InstantiationException(Class<?> clazz) {
+        super(clazz.getName());
+    }
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Integer.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Integer.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Integer.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Integer.java Sat May  2 08:09:50 2009
@@ -18,17 +18,13 @@
 package java.lang;
 
 /**
+ * The wrapper for the primitive type {@code int}.
  * <p>
- * Integer is the wrapper for the primitive type <code>int</code>.
- * </p>
- * 
- * <p>
- * As with the specification, this implementation relied on code laid out in <a
+ * As with the specification, this implementation relies on code laid out in <a
  * href="http://www.hackersdelight.org/">Henry S. Warren, Jr.'s Hacker's
  * Delight, (Addison Wesley, 2002)</a> as well as <a
  * href="http://aggregate.org/MAGIC/">The Aggregate's Magic Algorithms</a>.
- * </p>
- * 
+ *
  * @see java.lang.Number
  * @since 1.1
  */
@@ -42,25 +38,19 @@
     private final int value;
 
     /**
-     * <p>
-     * Constant for the maximum <code>int</code> value, 2<sup>31</sup>-1.
-     * </p>
+     * Constant for the maximum {@code int} value, 2<sup>31</sup>-1.
      */
     public static final int MAX_VALUE = 0x7FFFFFFF;
 
     /**
-     * <p>
-     * Constant for the minimum <code>int</code> value, -2<sup>31</sup>.
-     * </p>
+     * Constant for the minimum {@code int} value, -2<sup>31</sup>.
      */
     public static final int MIN_VALUE = 0x80000000;
 
     /**
-     * <p>
-     * Constant for the number of bits to represent an <code>int</code> in
-     * two's compliment form.
-     * </p>
-     * 
+     * Constant for the number of bits needed to represent an {@code int} in
+     * two's complement form.
+     *
      * @since 1.5
      */
     public static final int SIZE = 32;
@@ -74,7 +64,7 @@
             10000000, 1000000, 100000, 10000, 1000, 100, 10, 1 };
     
     /**
-     * The java.lang.Class that represents this class.
+     * The {@link Class} object that represents the primitive type {@code int}.
      */
     @SuppressWarnings("unchecked")
     public static final Class<Integer> TYPE = (Class<Integer>) new int[0]
@@ -84,52 +74,45 @@
     // defined to be "java.lang.Integer.TYPE";
 
     /**
-     * Constructs a new instance of the receiver which represents the int valued
-     * argument.
+     * Constructs a new {@code Integer} with the specified primitive integer
+     * value.
      * 
      * @param value
-     *            the int to store in the new instance.
+     *            the primitive integer value to store in the new instance.
      */
     public Integer(int value) {
         this.value = value;
     }
 
     /**
-     * Constructs a new instance of this class given a string.
+     * Constructs a new {@code Integer} from the specified string.
      * 
      * @param string
-     *            a string representation of an int quantity.
-     * @exception NumberFormatException
-     *                if the argument could not be parsed as an int quantity.
+     *            the string representation of an integer value.
+     * @throws NumberFormatException
+     *             if {@code string} can not be decoded into an integer value.
+     * @see #parseInt(String)
      */
     public Integer(String string) throws NumberFormatException {
         this(parseInt(string));
     }
 
-    /**
-     * Answers the byte value which the receiver represents
-     * 
-     * @return byte the value of the receiver.
-     */
     @Override
     public byte byteValue() {
         return (byte) value;
     }
 
     /**
-     * <p>
-     * Compares this <code>Integer</code> to the <code>Integer</code>
-     * passed. If this instance's value is equal to the value of the instance
-     * passed, then 0 is returned. If this instance's value is less than the
-     * value of the instance passed, then a negative value is returned. If this
-     * instance's value is greater than the value of the instance passed, then a
-     * positive value is returned.
-     * </p>
+     * Compares this object to the specified integer object to determine their
+     * relative order.
      * 
      * @param object
-     *            The instance to compare to.
-     * @throws NullPointerException
-     *             if <code>object</code> is <code>null</code>.
+     *            the integer object to compare this object to.
+     * @return a negative value if the value of this integer is less than the
+     *         value of {@code object}; 0 if the value of this integer and the
+     *         value of {@code object} are equal; a positive value if the value
+     *         of this integer is greater than the value of {@code object}.
+     * @see java.lang.Comparable
      * @since 1.2
      */
     public int compareTo(Integer object) {
@@ -137,16 +120,17 @@
     }
 
     /**
-     * Parses the string argument as if it was an int value and returns the
-     * result. Throws NumberFormatException if the string does not represent an
-     * int quantity. The string may be a hexadecimal ("0x..."), octal ("0..."),
-     * or decimal ("...") representation of an integer
+     * Parses the specified string and returns a {@code Integer} instance if the
+     * string can be decoded into an integer value. The string may be an
+     * optional minus sign "-" followed by a hexadecimal ("0x..." or "#..."),
+     * octal ("0..."), or decimal ("...") representation of an integer.
      * 
      * @param string
-     *            a string representation of an int quantity.
-     * @return Integer the value represented by the argument
-     * @exception NumberFormatException
-     *                if the argument could not be parsed as an int quantity.
+     *            a string representation of an integer value.
+     * @return an {@code Integer} containing the value represented by
+     *         {@code string}.
+     * @throws NumberFormatException
+     *             if {@code string} can not be parsed as an integer value.
      */
     public static Integer decode(String string) throws NumberFormatException {
         int length = string.length(), i = 0;
@@ -186,28 +170,20 @@
         return valueOf(result);
     }
 
-    /**
-     * Answers the double value which the receiver represents
-     * 
-     * @return double the value of the receiver.
-     */
     @Override
     public double doubleValue() {
         return value;
     }
 
     /**
-     * Compares the argument to the receiver, and answers true if they represent
-     * the <em>same</em> object using a class specific comparison.
-     * <p>
-     * In this case, the argument must also be an Integer, and the receiver and
-     * argument must represent the same int value.
+     * Compares this instance with the specified object and indicates if they
+     * are equal. In order to be equal, {@code o} must be an instance of
+     * {@code Integer} and have the same integer value as this object.
      * 
      * @param o
-     *            the object to compare with this object
-     * @return <code>true</code> if the object is the same as this object
-     *         <code>false</code> if it is different from this object
-     * @see #hashCode
+     *            the object to compare this integer with.
+     * @return {@code true} if the specified object is equal to this
+     *         {@code Integer}; {@code false} otherwise.
      */
     @Override
     public boolean equals(Object o) {
@@ -215,24 +191,21 @@
                 && (value == ((Integer) o).value);
     }
 
-    /**
-     * Answers the float value which the receiver represents
-     * 
-     * @return float the value of the receiver.
-     */
     @Override
     public float floatValue() {
         return value;
     }
 
     /**
-     * Answers an Integer representing the integer value of the property named
-     * by the argument. If the property could not be found, or its value could
-     * not be parsed as an integer, answer null.
+     * Returns the {@code Integer} value of the system property identified by
+     * {@code string}. Returns {@code null} if {@code string} is {@code null}
+     * or empty, if the property can not be found or if its value can not be
+     * parsed as an integer.
      * 
      * @param string
-     *            The name of the desired integer property.
-     * @return Integer An Integer representing the value of the property.
+     *            the name of the requested system property.
+     * @return the requested property's value as an {@code Integer} or
+     *         {@code null}.
      */
     public static Integer getInteger(String string) {
         if (string == null || string.length() == 0) {
@@ -250,14 +223,18 @@
     }
 
     /**
-     * Answers an Integer representing the integer value of the property named
-     * by the argument. If the property could not be found, or its value could
-     * not be parsed as an integer, answer an Integer representing the second
-     * argument.
+     * Returns the {@code Integer} value of the system property identified by
+     * {@code string}. Returns the specified default value if {@code string} is
+     * {@code null} or empty, if the property can not be found or if its value
+     * can not be parsed as an integer.
      * 
      * @param string
-     *            The name of the desired integer property.
-     * @return Integer An Integer representing the value of the property.
+     *            the name of the requested system property.
+     * @param defaultValue
+     *            the default value that is returned if there is no integer
+     *            system property with the requested name.
+     * @return the requested property's value as an {@code Integer} or the
+     *         default value.
      */
     public static Integer getInteger(String string, int defaultValue) {
         if (string == null || string.length() == 0) {
@@ -275,13 +252,18 @@
     }
 
     /**
-     * Answers an Integer representing the integer value of the property named
-     * by the argument. If the property could not be found, or its value could
-     * not be parsed as an integer, answer the second argument.
+     * Returns the {@code Integer} value of the system property identified by
+     * {@code string}. Returns the specified default value if {@code string} is
+     * {@code null} or empty, if the property can not be found or if its value
+     * can not be parsed as an integer.
      * 
      * @param string
-     *            The name of the desired integer property.
-     * @return Integer An Integer representing the value of the property.
+     *            the name of the requested system property.
+     * @param defaultValue
+     *            the default value that is returned if there is no integer
+     *            system property with the requested name.
+     * @return the requested property's value as an {@code Integer} or the
+     *         default value.
      */
     public static Integer getInteger(String string, Integer defaultValue) {
         if (string == null || string.length() == 0) {
@@ -298,68 +280,56 @@
         }
     }
 
-    /**
-     * Answers an integer hash code for the receiver. Any two objects which
-     * answer <code>true</code> when passed to <code>equals</code> must
-     * answer the same value for this method.
-     * 
-     * @return the receiver's hash
-     * 
-     * @see #equals
-     */
     @Override
     public int hashCode() {
         return value;
     }
 
     /**
-     * Answers the int value which the receiver represents
+     * Gets the primitive value of this int.
      * 
-     * @return int the value of the receiver.
+     * @return this object's primitive value.
      */
     @Override
     public int intValue() {
         return value;
     }
 
-    /**
-     * Answers the long value which the receiver represents
-     * 
-     * @return long the value of the receiver.
-     */
     @Override
     public long longValue() {
         return value;
     }
 
     /**
-     * Parses the string argument as if it was an int value and returns the
-     * result. Throws NumberFormatException if the string does not represent an
-     * int quantity.
+     * Parses the specified string as a signed decimal integer value. The ASCII
+     * character \u002d ('-') is recognized as the minus sign.
      * 
      * @param string
-     *            a string representation of an int quantity.
-     * @return int the value represented by the argument
-     * @exception NumberFormatException
-     *                if the argument could not be parsed as an int quantity.
+     *            the string representation of an integer value.
+     * @return the primitive integer value represented by {@code string}.
+     * @throws NumberFormatException
+     *             if {@code string} is {@code null}, has a length of zero or
+     *             can not be parsed as an integer value.
      */
     public static int parseInt(String string) throws NumberFormatException {
         return parseInt(string, 10);
     }
 
     /**
-     * Parses the string argument as if it was an int value and returns the
-     * result. Throws NumberFormatException if the string does not represent an
-     * int quantity. The second argument specifies the radix to use when parsing
-     * the value.
+     * Parses the specified string as a signed integer value using the specified
+     * radix. The ASCII character \u002d ('-') is recognized as the minus sign.
      * 
      * @param string
-     *            a string representation of an int quantity.
+     *            the string representation of an integer value.
      * @param radix
-     *            the base to use for conversion.
-     * @return int the value represented by the argument
-     * @exception NumberFormatException
-     *                if the argument could not be parsed as an int quantity.
+     *            the radix to use when parsing.
+     * @return the primitive integer value represented by {@code string} using
+     *         {@code radix}.
+     * @throws NumberFormatException
+     *             if {@code string} is {@code null} or has a length of zero,
+     *             {@code radix < Character.MIN_RADIX},
+     *             {@code radix > Character.MAX_RADIX}, or if {@code string}
+     *             can not be parsed as an integer value.
      */
     public static int parseInt(String string, int radix)
             throws NumberFormatException {
@@ -406,23 +376,18 @@
         return result;
     }
 
-    /**
-     * Answers the short value which the receiver represents
-     * 
-     * @return short the value of the receiver.
-     */
     @Override
     public short shortValue() {
         return (short) value;
     }
 
     /**
-     * Answers a string containing '0' and '1' characters which describe the
-     * binary representation of the argument.
+     * Converts the specified integer into its binary string representation. The
+     * returned string is a concatenation of '0' and '1' characters.
      * 
      * @param i
-     *            an int to get the binary representation of
-     * @return String the binary representation of the argument
+     *            the integer to convert.
+     * @return the binary string representation of {@code i}.
      */
     public static String toBinaryString(int i) {
         int count = 1, j = i;
@@ -444,12 +409,13 @@
     }
 
     /**
-     * Answers a string containing characters in the range 0..9, a..f which
-     * describe the hexadecimal representation of the argument.
+     * Converts the specified integer into its hexadecimal string
+     * representation. The returned string is a concatenation of characters from
+     * '0' to '9' and 'a' to 'f'.
      * 
      * @param i
-     *            an int to get the hex representation of
-     * @return String the hex representation of the argument
+     *            the integer to convert.
+     * @return the hexadecimal string representation of {@code i}.
      */
     public static String toHexString(int i) {
         int count = 1, j = i;
@@ -477,12 +443,12 @@
     }
 
     /**
-     * Answers a string containing characters in the range 0..7 which describe
-     * the octal representation of the argument.
+     * Converts the specified integer into its octal string representation. The
+     * returned string is a concatenation of characters from '0' to '7'.
      * 
      * @param i
-     *            an int to get the octal representation of
-     * @return String the hex representation of the argument
+     *            the integer to convert.
+     * @return the octal string representation of {@code i}.
      */
     public static String toOctalString(int i) {
         int count = 1, j = i;
@@ -503,24 +469,19 @@
         return new String(0, buffer.length, buffer);
     }
 
-    /**
-     * Answers a string containing a concise, human-readable description of the
-     * receiver.
-     * 
-     * @return a printable representation for the receiver.
-     */
     @Override
     public String toString() {
         return Integer.toString(value);
     }
 
     /**
-     * Answers a string containing characters in the range 0..9 which describe
-     * the decimal representation of the argument.
+     * Converts the specified integer into its decimal string representation.
+     * The returned string is a concatenation of a minus sign if the number is
+     * negative and characters from '0' to '9'.
      * 
      * @param value
-     *            an int to get the representation of
-     * @return String the representation of the argument
+     *            the integer to convert.
+     * @return the decimal string representation of {@code value}.
      */
     public static String toString(int value) {
         if (value == 0) {
@@ -613,15 +574,18 @@
     }
 
     /**
-     * Answers a string containing characters in the range 0..9, a..z (depending
-     * on the radix) which describe the representation of the argument in that
-     * radix.
+     * Converts the specified integer into a string representation based on the
+     * specified radix. The returned string is a concatenation of a minus sign
+     * if the number is negative and characters from '0' to '9' and 'a' to 'z',
+     * depending on the radix. If {@code radix} is not in the interval defined
+     * by {@code Character.MIN_RADIX} and {@code Character.MAX_RADIX} then 10 is
+     * used as the base for the conversion.
      * 
      * @param i
-     *            an int to get the representation of
+     *            the integer to convert.
      * @param radix
-     *            the base to use for conversion.
-     * @return String the representation of the argument
+     *            the base to use for the conversion.
+     * @return the string representation of {@code i}.
      */
     public static String toString(int i, int radix) {
         if (radix < Character.MIN_RADIX || radix > Character.MAX_RADIX) {
@@ -658,33 +622,37 @@
     }
 
     /**
-     * Parses the string argument as if it was an int value and returns the
-     * result. Throws NumberFormatException if the string does not represent an
-     * int quantity.
+     * Parses the specified string as a signed decimal integer value.
      * 
      * @param string
-     *            a string representation of an int quantity.
-     * @return Integer the value represented by the argument
-     * @exception NumberFormatException
-     *                if the argument could not be parsed as an int quantity.
+     *            the string representation of an integer value.
+     * @return an {@code Integer} instance containing the integer value
+     *         represented by {@code string}.
+     * @throws NumberFormatException
+     *             if {@code string} is {@code null}, has a length of zero or
+     *             can not be parsed as an integer value.
+     * @see #parseInt(String)
      */
     public static Integer valueOf(String string) throws NumberFormatException {
         return valueOf(parseInt(string));
     }
 
     /**
-     * Parses the string argument as if it was an int value and returns the
-     * result. Throws NumberFormatException if the string does not represent an
-     * int quantity. The second argument specifies the radix to use when parsing
-     * the value.
+     * Parses the specified string as a signed integer value using the specified
+     * radix.
      * 
      * @param string
-     *            a string representation of an int quantity.
+     *            the string representation of an integer value.
      * @param radix
-     *            the base to use for conversion.
-     * @return Integer the value represented by the argument
-     * @exception NumberFormatException
-     *                if the argument could not be parsed as an int quantity.
+     *            the radix to use when parsing.
+     * @return an {@code Integer} instance containing the integer value
+     *         represented by {@code string} using {@code radix}.
+     * @throws NumberFormatException
+     *             if {@code string} is {@code null} or has a length of zero,
+     *             {@code radix < Character.MIN_RADIX},
+     *             {@code radix > Character.MAX_RADIX}, or if {@code string}
+     *             can not be parsed as an integer value.
+     * @see #parseInt(String, int)
      */
     public static Integer valueOf(String string, int radix)
             throws NumberFormatException {
@@ -692,15 +660,14 @@
     }
 
     /**
-     * <p>
-     * Determines the highest (leftmost) bit that is 1 and returns the value
-     * that is the bit mask for that bit. This is sometimes referred to as the
-     * Most Significant 1 Bit.
-     * </p>
+     * Determines the highest (leftmost) bit of the specified integer that is 1
+     * and returns the bit mask value for that bit. This is also referred to as
+     * the Most Significant 1 Bit. Returns zero if the specified integer is
+     * zero.
      * 
      * @param i
-     *            The <code>int</code> to interrogate.
-     * @return The bit mask indicating the highest 1 bit.
+     *            the integer to examine.
+     * @return the bit mask indicating the highest 1 bit in {@code i}.
      * @since 1.5
      */
     public static int highestOneBit(int i) {
@@ -713,15 +680,14 @@
     }
 
     /**
-     * <p>
-     * Determines the lowest (rightmost) bit that is 1 and returns the value
-     * that is the bit mask for that bit. This is sometimes referred to as the
-     * Least Significant 1 Bit.
-     * </p>
+     * Determines the lowest (rightmost) bit of the specified integer that is 1
+     * and returns the bit mask value for that bit. This is also referred
+     * to as the Least Significant 1 Bit. Returns zero if the specified integer
+     * is zero.
      * 
      * @param i
-     *            The <code>int</code> to interrogate.
-     * @return The bit mask indicating the lowest 1 bit.
+     *            the integer to examine.
+     * @return the bit mask indicating the lowest 1 bit in {@code i}.
      * @since 1.5
      */
     public static int lowestOneBit(int i) {
@@ -729,14 +695,12 @@
     }
 
     /**
-     * <p>
-     * Determines the number of leading zeros in the <code>int</code> passed
-     * prior to the {@link #highestOneBit(int) highest one bit}.
-     * </p>
-     * 
+     * Determines the number of leading zeros in the specified integer prior to
+     * the {@link #highestOneBit(int) highest one bit}.
+     *
      * @param i
-     *            The <code>int</code> to process.
-     * @return The number of leading zeros.
+     *            the integer to examine.
+     * @return the number of leading zeros in {@code i}.
      * @since 1.5
      */
     public static int numberOfLeadingZeros(int i) {
@@ -749,14 +713,12 @@
     }
 
     /**
-     * <p>
-     * Determines the number of trailing zeros in the <code>int</code> passed
-     * after the {@link #lowestOneBit(int) lowest one bit}.
-     * </p>
-     * 
+     * Determines the number of trailing zeros in the specified integer after
+     * the {@link #lowestOneBit(int) lowest one bit}.
+     *
      * @param i
-     *            The <code>int</code> to process.
-     * @return The number of trailing zeros.
+     *            the integer to examine.
+     * @return the number of trailing zeros in {@code i}.
      * @since 1.5
      */
     public static int numberOfTrailingZeros(int i) {
@@ -764,14 +726,12 @@
     }
 
     /**
-     * <p>
-     * Counts the number of 1 bits in the <code>int</code> value passed; this
-     * is sometimes referred to as a population count.
-     * </p>
-     * 
+     * Counts the number of 1 bits in the specified integer; this is also
+     * referred to as population count.
+     *
      * @param i
-     *            The <code>int</code> value to process.
-     * @return The number of 1 bits.
+     *            the integer to examine.
+     * @return the number of 1 bits in {@code i}.
      * @since 1.5
      */
     public static int bitCount(int i) {
@@ -784,16 +744,14 @@
     }
 
     /**
-     * <p>
-     * Rotates the bits of <code>i</code> to the left by the
-     * <code>distance</code> bits.
-     * </p>
-     * 
+     * Rotates the bits of the specified integer to the left by the specified
+     * number of bits.
+     *
      * @param i
-     *            The <code>int</code> value to rotate left.
+     *            the integer value to rotate left.
      * @param distance
-     *            The number of bits to rotate.
-     * @return The rotated value.
+     *            the number of bits to rotate.
+     * @return the rotated value.
      * @since 1.5
      */
     public static int rotateLeft(int i, int distance) {
@@ -809,16 +767,14 @@
     }
 
     /**
-     * <p>
-     * Rotates the bits of <code>i</code> to the right by the
-     * <code>distance</code> bits.
-     * </p>
-     * 
+     * Rotates the bits of the specified integer to the right by the specified
+     * number of bits.
+     *
      * @param i
-     *            The <code>int</code> value to rotate right.
+     *            the integer value to rotate right.
      * @param distance
-     *            The number of bits to rotate.
-     * @return The rotated value.
+     *            the number of bits to rotate.
+     * @return the rotated value.
      * @since 1.5
      */
     public static int rotateRight(int i, int distance) {
@@ -834,13 +790,11 @@
     }
 
     /**
-     * <p>
-     * Reverses the bytes of a <code>int</code>.
-     * </p>
+     * Reverses the order of the bytes of the specified integer.
      * 
      * @param i
-     *            The <code>int</code> to reverse.
-     * @return The reversed value.
+     *            the integer value for which to reverse the byte order.
+     * @return the reversed value.
      * @since 1.5
      */
     public static int reverseBytes(int i) {
@@ -852,13 +806,11 @@
     }
 
     /**
-     * <p>
-     * Reverses the bytes of a <code>int</code>.
-     * </p>
+     * Reverses the order of the bits of the specified integer.
      * 
      * @param i
-     *            The <code>int</code> to reverse.
-     * @return The reversed value.
+     *            the integer value for which to reverse the bit order.
+     * @return the reversed value.
      * @since 1.5
      */
     public static int reverse(int i) {
@@ -870,15 +822,13 @@
     }
 
     /**
-     * <p>
-     * The <code>signum</code> function for <code>int</code> values. This
-     * method returns -1 for negative values, 1 for positive values and 0 for
-     * the value 0.
-     * </p>
+     * Returns the value of the {@code signum} function for the specified
+     * integer.
      * 
      * @param i
-     *            The <code>int</code> value.
-     * @return -1 if negative, 1 if positive otherwise 0.
+     *            the integer value to check.
+     * @return -1 if {@code i} is negative, 1 if {@code i} is positive, 0 if
+     *         {@code i} is zero.
      * @since 1.5
      */
     public static int signum(int i) {
@@ -886,15 +836,15 @@
     }
 
     /**
+     * Returns a {@code Integer} instance for the specified integer value.
      * <p>
-     * Returns a <code>Integer</code> instance for the <code>int</code>
-     * value passed. This method is preferred over the constructor, as this
-     * method may maintain a cache of instances.
-     * </p>
-     * 
+     * If it is not necessary to get a new {@code Integer} instance, it is
+     * recommended to use this method instead of the constructor, since it
+     * maintains a cache of instances which may result in better performance.
+     *
      * @param i
-     *            The int value.
-     * @return A <code>Integer</code> instance.
+     *            the integer value to store in the instance.
+     * @return a {@code Integer} instance containing {@code i}.
      * @since 1.5
      */
     public static Integer valueOf(int i) {
@@ -909,7 +859,6 @@
         /**
          * <p>
          * A cache of instances used by {@link Integer#valueOf(int)} and auto-boxing.
-         * </p>
          */
         static final Integer[] CACHE = new Integer[256];
 

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InternalError.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InternalError.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InternalError.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InternalError.java Sat May  2 08:09:50 2009
@@ -17,30 +17,30 @@
 
 package java.lang;
 
-
 /**
- * This error is thrown when the VM notices that it has gotten into a state
- * which it does not understand.
+ * Thrown when the virtual machine notices that it has gotten into an undefined
+ * state.
  */
 public class InternalError extends VirtualMachineError {
 
     private static final long serialVersionUID = -9062593416125562365L;
 
     /**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
-	public InternalError() {
-		super();
-	}
+     * Constructs a new {@code InternalError} that includes the current stack
+     * trace.
+     */
+    public InternalError() {
+        super();
+    }
 
-	/**
-	 * Constructs a new instance of this class with its walkback and message
-	 * filled in.
-	 * 
-	 * @param detailMessage
-	 *            String The detail message for the exception.
-	 */
-	public InternalError(String detailMessage) {
-		super(detailMessage);
-	}
+    /**
+     * Constructs a new {@code InternalError} with the current stack trace and
+     * the specified detail message.
+     * 
+     * @param detailMessage
+     *            the detail message for this error.
+     */
+    public InternalError(String detailMessage) {
+        super(detailMessage);
+    }
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InterruptedException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InterruptedException.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InterruptedException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/InterruptedException.java Sat May  2 08:09:50 2009
@@ -17,30 +17,30 @@
 
 package java.lang;
 
-
 /**
- * This exception is thrown when a waiting thread is activated before the
- * condition it was waiting on has been satisfied.
+ * Thrown when a waiting thread is activated before the condition it was waiting
+ * for has been satisfied.
  */
 public class InterruptedException extends Exception {
 
     private static final long serialVersionUID = 6700697376100628473L;
 
     /**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
-	public InterruptedException() {
-		super();
-	}
+     * Constructs a new {@code InterruptedException} that includes the current
+     * stack trace.
+     */
+    public InterruptedException() {
+        super();
+    }
 
-	/**
-	 * Constructs a new instance of this class with its walkback and message
-	 * filled in.
-	 * 
-	 * @param detailMessage
-	 *            String The detail message for the exception.
-	 */
-	public InterruptedException(String detailMessage) {
-		super(detailMessage);
-	}
+    /**
+     * Constructs a new {@code InterruptedException} with the current stack
+     * trace and the specified detail message.
+     * 
+     * @param detailMessage
+     *            the detail message for this exception.
+     */
+    public InterruptedException(String detailMessage) {
+        super(detailMessage);
+    }
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Iterable.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Iterable.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Iterable.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Iterable.java Sat May  2 08:09:50 2009
@@ -19,16 +19,17 @@
 import java.util.Iterator;
 
 /**
- * <p>Implementations of this interface can be used within a <code>foreach</code>
- * statement.</p>
+ * Objects of classes that implement this interface can be used within a
+ * {@code foreach} statement.
+ *
  * @since 1.5
  */
 public interface Iterable<T> {
 
     /**
-     * <p>Returns an {@link Iterator} for the elements in this object.</p>
+     * Returns an {@link Iterator} for the elements in this object.
      * 
-     * @return An <code>Iterator</code> instance.
+     * @return An {@code Iterator} instance.
      */
     Iterator<T> iterator();
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/LinkageError.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/LinkageError.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/LinkageError.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/LinkageError.java Sat May  2 08:09:50 2009
@@ -19,8 +19,8 @@
 
 
 /**
- * This class is the superclass of all classes which represent errors that occur
- * when loading and linking class files.
+ * {@code LinkageError} is the superclass of all error classes that occur when
+ * loading and linking class files.
  * 
  * @see Error
  */
@@ -29,20 +29,21 @@
     private static final long serialVersionUID = 3579600108157160122L;
 
     /**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
-	public LinkageError() {
-		super();
-	}
+     * Constructs a new {@code LinkageError} that includes the current stack
+     * trace.
+     */
+    public LinkageError() {
+        super();
+    }
 
-	/**
-	 * Constructs a new instance of this class with its walkback and message
-	 * filled in.
-	 * 
-	 * @param detailMessage
-	 *            String The detail message for the exception.
-	 */
-	public LinkageError(String detailMessage) {
-		super(detailMessage);
-	}
+    /**
+     * Constructs a new {@code LinkageError} with the current stack trace and
+     * the specified detail message.
+     * 
+     * @param detailMessage
+     *            the detail message for this error.
+     */
+    public LinkageError(String detailMessage) {
+        super(detailMessage);
+    }
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Long.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Long.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Long.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Long.java Sat May  2 08:09:50 2009
@@ -18,17 +18,13 @@
 package java.lang;
 
 /**
+ * The wrapper for the primitive type {@code long}.
  * <p>
- * Long is the wrapper for the primitive type <code>long</code>.
- * </p>
- * 
- * <p>
- * As with the specification, this implementation relied on code laid out in <a
+ * As with the specification, this implementation relies on code laid out in <a
  * href="http://www.hackersdelight.org/">Henry S. Warren, Jr.'s Hacker's
  * Delight, (Addison Wesley, 2002)</a> as well as <a
  * href="http://aggregate.org/MAGIC/">The Aggregate's Magic Algorithms</a>.
- * </p>
- * 
+ *
  * @see java.lang.Number
  * @since 1.0
  */
@@ -42,21 +38,17 @@
     private final long value;
 
     /**
-     * <p>
-     * Constant for the maximum <code>long</code> value, 2<sup>63</sup>-1.
-     * </p>
+     * Constant for the maximum {@code long} value, 2<sup>63</sup>-1.
      */
     public static final long MAX_VALUE = 0x7FFFFFFFFFFFFFFFL;
 
     /**
-     * <p>
-     * Constant for the minimum <code>long</code> value, -2<sup>31</sup>.
-     * </p>
+     * Constant for the minimum {@code long} value, -2<sup>63</sup>.
      */
     public static final long MIN_VALUE = 0x8000000000000000L;
 
     /**
-     * The java.lang.Class that represents this class.
+     * The {@link Class} object that represents the primitive type {@code long}.
      */
     @SuppressWarnings("unchecked")
     public static final Class<Long> TYPE = (Class<Long>) new long[0].getClass()
@@ -66,63 +58,53 @@
     // defined to be "java.lang.Long.TYPE";
 
     /**
-     * <p>
-     * Constant for the number of bits to represent a <code>long</code> in
-     * two's compliment form.
-     * </p>
-     * 
+     * Constant for the number of bits needed to represent a {@code long} in
+     * two's complement form.
+     *
      * @since 1.5
      */
     public static final int SIZE = 64;
 
 
     /**
-     * Constructs a new instance of the receiver which represents the long
-     * valued argument.
+     * Constructs a new {@code Long} with the specified primitive long value.
      * 
      * @param value
-     *            the long to store in the new instance.
+     *            the primitive long value to store in the new instance.
      */
     public Long(long value) {
         this.value = value;
     }
 
     /**
-     * Constructs a new instance of this class given a string.
+     * Constructs a new {@code Long} from the specified string.
      * 
      * @param string
-     *            a string representation of an long quantity.
-     * @exception NumberFormatException
-     *                if the argument could not be parsed as a long quantity.
+     *            the string representation of a long value.
+     * @throws NumberFormatException
+     *             if {@code string} can not be decoded into a long value.
+     * @see #parseLong(String)
      */
     public Long(String string) throws NumberFormatException {
         this(parseLong(string));
     }
 
-    /**
-     * Answers the byte value which the receiver represents
-     * 
-     * @return byte the value of the receiver.
-     */
     @Override
     public byte byteValue() {
         return (byte) value;
     }
 
     /**
-     * <p>
-     * Compares this <code>Long</code> to the <code>Long</code> passed. If
-     * this instance's value is equal to the value of the instance passed, then
-     * 0 is returned. If this instance's value is less than the value of the
-     * instance passed, then a negative value is returned. If this instance's
-     * value is greater than the value of the instance passed, then a positive
-     * value is returned.
-     * </p>
+     * Compares this object to the specified long object to determine their
+     * relative order.
      * 
      * @param object
-     *            The instance to compare to.
-     * @throws NullPointerException
-     *             if <code>object</code> is <code>null</code>.
+     *            the long object to compare this object to.
+     * @return a negative value if the value of this long is less than the value
+     *         of {@code object}; 0 if the value of this long and the value of
+     *         {@code object} are equal; a positive value if the value of this
+     *         long is greater than the value of {@code object}.
+     * @see java.lang.Comparable
      * @since 1.2
      */
     public int compareTo(Long object) {
@@ -130,16 +112,16 @@
     }
 
     /**
-     * Parses the string argument as if it was a long value and returns the
-     * result. Throws NumberFormatException if the string does not represent a
-     * long quantity. The string may be a hexadecimal ("0x..."), octal ("0..."),
-     * or decimal ("...") representation of a long.
+     * Parses the specified string and returns a {@code Long} instance if the
+     * string can be decoded into a long value. The string may be an optional
+     * minus sign "-" followed by a hexadecimal ("0x..." or "#..."), octal
+     * ("0..."), or decimal ("...") representation of a long.
      * 
      * @param string
-     *            a string representation of an long quantity.
-     * @return Long the value represented by the argument
-     * @exception NumberFormatException
-     *                if the argument could not be parsed as an long quantity.
+     *            a string representation of a long value.
+     * @return a {@code Long} containing the value represented by {@code string}.
+     * @throws NumberFormatException
+     *             if {@code string} can not be parsed as a long value.
      */
     public static Long decode(String string) throws NumberFormatException {
         int length = string.length(), i = 0;
@@ -181,28 +163,20 @@
         return valueOf(result);
     }
 
-    /**
-     * Answers the double value which the receiver represents
-     * 
-     * @return double the value of the receiver.
-     */
     @Override
     public double doubleValue() {
         return value;
     }
 
     /**
-     * Compares the argument to the receiver, and answers true if they represent
-     * the <em>same</em> object using a class specific comparison.
-     * <p>
-     * In this case, the argument must also be an Long, and the receiver and
-     * argument must represent the same long value.
+     * Compares this instance with the specified object and indicates if they
+     * are equal. In order to be equal, {@code o} must be an instance of
+     * {@code Long} and have the same long value as this object.
      * 
      * @param o
-     *            the object to compare with this object
-     * @return <code>true</code> if the object is the same as this object
-     *         <code>false</code> if it is different from this object
-     * @see #hashCode
+     *            the object to compare this long with.
+     * @return {@code true} if the specified object is equal to this
+     *         {@code Long}; {@code false} otherwise.
      */
     @Override
     public boolean equals(Object o) {
@@ -210,24 +184,20 @@
                 && (value == ((Long) o).value);
     }
 
-    /**
-     * Answers the float value which the receiver represents
-     * 
-     * @return float the value of the receiver.
-     */
     @Override
     public float floatValue() {
         return value;
     }
 
     /**
-     * Answers a Long representing the long value of the property named by the
-     * argument. If the property could not be found, or its value could not be
-     * parsed as a long, answer null.
+     * Returns the {@code Long} value of the system property identified by
+     * {@code string}. Returns {@code null} if {@code string} is {@code null}
+     * or empty, if the property can not be found or if its value can not be
+     * parsed as a long.
      * 
      * @param string
-     *            The name of the desired integer property.
-     * @return Long A Long representing the value of the property.
+     *            the name of the requested system property.
+     * @return the requested property's value as a {@code Long} or {@code null}.
      */
     public static Long getLong(String string) {
         if (string == null || string.length() == 0) {
@@ -245,13 +215,18 @@
     }
 
     /**
-     * Answers a Long representing the long value of the property named by the
-     * argument. If the property could not be found, or its value could not be
-     * parsed as a long, answer a Long representing the second argument.
+     * Returns the {@code Long} value of the system property identified by
+     * {@code string}. Returns the specified default value if {@code string} is
+     * {@code null} or empty, if the property can not be found or if its value
+     * can not be parsed as a long.
      * 
      * @param string
-     *            The name of the desired long property.
-     * @return Long An Long representing the value of the property.
+     *            the name of the requested system property.
+     * @param defaultValue
+     *            the default value that is returned if there is no long system
+     *            property with the requested name.
+     * @return the requested property's value as a {@code Long} or the default
+     *         value.
      */
     public static Long getLong(String string, long defaultValue) {
         if (string == null || string.length() == 0) {
@@ -269,13 +244,18 @@
     }
 
     /**
-     * Answers an Long representing the long value of the property named by the
-     * argument. If the property could not be found, or its value could not be
-     * parsed as an long, answer the second argument.
+     * Returns the {@code Long} value of the system property identified by
+     * {@code string}. Returns the specified default value if {@code string} is
+     * {@code null} or empty, if the property can not be found or if its value
+     * can not be parsed as a long.
      * 
      * @param string
-     *            The name of the desired long property.
-     * @return Long An Long representing the value of the property.
+     *            the name of the requested system property.
+     * @param defaultValue
+     *            the default value that is returned if there is no long system
+     *            property with the requested name.
+     * @return the requested property's value as a {@code Long} or the default
+     *         value.
      */
     public static Long getLong(String string, Long defaultValue) {
         if (string == null || string.length() == 0) {
@@ -292,34 +272,20 @@
         }
     }
 
-    /**
-     * Answers an integer hash code for the receiver. Any two objects which
-     * answer <code>true</code> when passed to <code>equals</code> must
-     * answer the same value for this method.
-     * 
-     * @return the receiver's hash
-     * 
-     * @see #equals
-     */
     @Override
     public int hashCode() {
         return (int) (value ^ (value >>> 32));
     }
 
-    /**
-     * Answers the int value which the receiver represents
-     * 
-     * @return int the value of the receiver.
-     */
     @Override
     public int intValue() {
         return (int) value;
     }
 
     /**
-     * Answers the long value which the receiver represents
+     * Gets the primitive value of this long.
      * 
-     * @return long the value of the receiver.
+     * @return this object's primitive value.
      */
     @Override
     public long longValue() {
@@ -327,33 +293,35 @@
     }
 
     /**
-     * Parses the string argument as if it was a long value and returns the
-     * result. Throws NumberFormatException if the string does not represent a
-     * long quantity.
+     * Parses the specified string as a signed decimal long value. The ASCII
+     * character \u002d ('-') is recognized as the minus sign.
      * 
      * @param string
-     *            a string representation of a long quantity.
-     * @return long the value represented by the argument
-     * @exception NumberFormatException
-     *                if the argument could not be parsed as a long quantity.
+     *            the string representation of a long value.
+     * @return the primitive long value represented by {@code string}.
+     * @throws NumberFormatException
+     *             if {@code string} is {@code null}, has a length of zero or
+     *             can not be parsed as a long value.
      */
     public static long parseLong(String string) throws NumberFormatException {
         return parseLong(string, 10);
     }
 
     /**
-     * Parses the string argument as if it was an long value and returns the
-     * result. Throws NumberFormatException if the string does not represent an
-     * long quantity. The second argument specifies the radix to use when
-     * parsing the value.
+     * Parses the specified string as a signed long value using the specified
+     * radix. The ASCII character \u002d ('-') is recognized as the minus sign.
      * 
      * @param string
-     *            a string representation of an long quantity.
+     *            the string representation of a long value.
      * @param radix
-     *            the base to use for conversion.
-     * @return long the value represented by the argument
-     * @exception NumberFormatException
-     *                if the argument could not be parsed as an long quantity.
+     *            the radix to use when parsing.
+     * @return the primitive long value represented by {@code string} using
+     *         {@code radix}.
+     * @throws NumberFormatException
+     *             if {@code string} is {@code null} or has a length of zero,
+     *             {@code radix < Character.MIN_RADIX},
+     *             {@code radix > Character.MAX_RADIX}, or if {@code string}
+     *             can not be parsed as a long value.
      */
     public static long parseLong(String string, int radix)
             throws NumberFormatException {
@@ -400,23 +368,18 @@
         return result;
     }
 
-    /**
-     * Answers the short value which the receiver represents
-     * 
-     * @return short the value of the receiver.
-     */
     @Override
     public short shortValue() {
         return (short) value;
     }
 
     /**
-     * Answers a string containing '0' and '1' characters which describe the
-     * binary representation of the argument.
+     * Converts the specified long value into its binary string representation.
+     * The returned string is a concatenation of '0' and '1' characters.
      * 
      * @param l
-     *            a long to get the binary representation of
-     * @return String the binary representation of the argument
+     *            the long value to convert.
+     * @return the binary string representation of {@code l}.
      */
     public static String toBinaryString(long l) {
         int count = 1;
@@ -439,12 +402,13 @@
     }
 
     /**
-     * Answers a string containing characters in the range 0..7, a..f which
-     * describe the hexadecimal representation of the argument.
+     * Converts the specified long value into its hexadecimal string
+     * representation. The returned string is a concatenation of characters from
+     * '0' to '9' and 'a' to 'f'.
      * 
      * @param l
-     *            a long to get the hex representation of
-     * @return String the hex representation of the argument
+     *            the long value to convert.
+     * @return the hexadecimal string representation of {@code l}.
      */
     public static String toHexString(long l) {
         int count = 1;
@@ -473,12 +437,12 @@
     }
 
     /**
-     * Answers a string containing characters in the range 0..7 which describe
-     * the octal representation of the argument.
+     * Converts the specified long value into its octal string representation.
+     * The returned string is a concatenation of characters from '0' to '7'.
      * 
      * @param l
-     *            a long to get the octal representation of
-     * @return String the octal representation of the argument
+     *            the long value to convert.
+     * @return the octal string representation of {@code l}.
      */
     public static String toOctalString(long l) {
         int count = 1;
@@ -500,39 +464,37 @@
         return new String(0, buffer.length, buffer);
     }
 
-    /**
-     * Answers a string containing a concise, human-readable description of the
-     * receiver.
-     * 
-     * @return a printable representation for the receiver.
-     */
     @Override
     public String toString() {
         return Long.toString(value);
     }
 
     /**
-     * Answers a string containing characters in the range 0..9 which describe
-     * the decimal representation of the argument.
+     * Converts the specified long value into its decimal string representation.
+     * The returned string is a concatenation of a minus sign if the number is
+     * negative and characters from '0' to '9'.
      * 
      * @param l
-     *            a long to get the representation of
-     * @return String the representation of the argument
+     *            the long to convert.
+     * @return the decimal string representation of {@code l}.
      */
     public static String toString(long l) {
         return toString(l, 10);
     }
 
     /**
-     * Answers a string containing characters in the range 0..9, a..z (depending
-     * on the radix) which describe the representation of the argument in that
-     * radix.
+     * Converts the specified long value into a string representation based on
+     * the specified radix. The returned string is a concatenation of a minus
+     * sign if the number is negative and characters from '0' to '9' and 'a' to
+     * 'z', depending on the radix. If {@code radix} is not in the interval
+     * defined by {@code Character.MIN_RADIX} and {@code Character.MAX_RADIX}
+     * then 10 is used as the base for the conversion.
      * 
      * @param l
-     *            a long to get the representation of
+     *            the long to convert.
      * @param radix
-     *            the base to use for conversion.
-     * @return String the representation of the argument
+     *            the base to use for the conversion.
+     * @return the string representation of {@code l}.
      */
     public static String toString(long l, int radix) {
         if (radix < Character.MIN_RADIX || radix > Character.MAX_RADIX) {
@@ -570,33 +532,37 @@
     }
 
     /**
-     * Parses the string argument as if it was an long value and returns the
-     * result. Throws NumberFormatException if the string does not represent an
-     * long quantity.
+     * Parses the specified string as a signed decimal long value.
      * 
      * @param string
-     *            a string representation of an long quantity.
-     * @return Long the value represented by the argument
-     * @exception NumberFormatException
-     *                if the argument could not be parsed as an long quantity.
+     *            the string representation of a long value.
+     * @return a {@code Long} instance containing the long value represented by
+     *         {@code string}.
+     * @throws NumberFormatException
+     *             if {@code string} is {@code null}, has a length of zero or
+     *             can not be parsed as a long value.
+     * @see #parseLong(String)
      */
     public static Long valueOf(String string) throws NumberFormatException {
         return valueOf(parseLong(string));
     }
 
     /**
-     * Parses the string argument as if it was an long value and returns the
-     * result. Throws NumberFormatException if the string does not represent an
-     * long quantity. The second argument specifies the radix to use when
-     * parsing the value.
+     * Parses the specified string as a signed long value using the specified
+     * radix.
      * 
      * @param string
-     *            a string representation of an long quantity.
+     *            the string representation of a long value.
      * @param radix
-     *            the base to use for conversion.
-     * @return Long the value represented by the argument
-     * @exception NumberFormatException
-     *                if the argument could not be parsed as an long quantity.
+     *            the radix to use when parsing.
+     * @return a {@code Long} instance containing the long value represented by
+     *         {@code string} using {@code radix}.
+     * @throws NumberFormatException
+     *             if {@code string} is {@code null} or has a length of zero,
+     *             {@code radix < Character.MIN_RADIX},
+     *             {@code radix > Character.MAX_RADIX}, or if {@code string}
+     *             can not be parsed as a long value.
+     * @see #parseLong(String, int)
      */
     public static Long valueOf(String string, int radix)
             throws NumberFormatException {
@@ -604,15 +570,14 @@
     }
 
     /**
-     * <p>
-     * Determines the highest (leftmost) bit that is 1 and returns the value
-     * that is the bit mask for that bit. This is sometimes referred to as the
-     * Most Significant 1 Bit.
-     * </p>
+     * Determines the highest (leftmost) bit of the specified long value that is
+     * 1 and returns the bit mask value for that bit. This is also referred to
+     * as the Most Significant 1 Bit. Returns zero if the specified long is
+     * zero.
      * 
      * @param lng
-     *            The <code>long</code> to interrogate.
-     * @return The bit mask indicating the highest 1 bit.
+     *            the long to examine.
+     * @return the bit mask indicating the highest 1 bit in {@code lng}.
      * @since 1.5
      */
     public static long highestOneBit(long lng) {
@@ -626,15 +591,14 @@
     }
 
     /**
-     * <p>
-     * Determines the lowest (rightmost) bit that is 1 and returns the value
-     * that is the bit mask for that bit. This is sometimes referred to as the
-     * Least Significant 1 Bit.
-     * </p>
+     * Determines the lowest (rightmost) bit of the specified long value that is
+     * 1 and returns the bit mask value for that bit. This is also referred to
+     * as the Least Significant 1 Bit. Returns zero if the specified long is
+     * zero.
      * 
      * @param lng
-     *            The <code>long</code> to interrogate.
-     * @return The bit mask indicating the lowest 1 bit.
+     *            the long to examine.
+     * @return the bit mask indicating the lowest 1 bit in {@code lng}.
      * @since 1.5
      */
     public static long lowestOneBit(long lng) {
@@ -642,14 +606,12 @@
     }
 
     /**
-     * <p>
-     * Determines the number of leading zeros in the <code>long</code> passed
-     * prior to the {@link #highestOneBit(long) highest one bit}.
-     * </p>
-     * 
+     * Determines the number of leading zeros in the specified long value prior
+     * to the {@link #highestOneBit(long) highest one bit}.
+     *
      * @param lng
-     *            The <code>long</code> to process.
-     * @return The number of leading zeros.
+     *            the long to examine.
+     * @return the number of leading zeros in {@code lng}.
      * @since 1.5
      */
     public static int numberOfLeadingZeros(long lng) {
@@ -663,14 +625,12 @@
     }
 
     /**
-     * <p>
-     * Determines the number of trailing zeros in the <code>long</code> passed
-     * after the {@link #lowestOneBit(long) lowest one bit}.
-     * </p>
-     * 
+     * Determines the number of trailing zeros in the specified long value after
+     * the {@link #lowestOneBit(long) lowest one bit}.
+     *
      * @param lng
-     *            The <code>long</code> to process.
-     * @return The number of trailing zeros.
+     *            the long to examine.
+     * @return the number of trailing zeros in {@code lng}.
      * @since 1.5
      */
     public static int numberOfTrailingZeros(long lng) {
@@ -678,14 +638,12 @@
     }
 
     /**
-     * <p>
-     * Counts the number of 1 bits in the <code>long</code> value passed; this
-     * is sometimes referred to as a population count.
-     * </p>
-     * 
+     * Counts the number of 1 bits in the specified long value; this is also
+     * referred to as population count.
+     *
      * @param lng
-     *            The <code>long</code> value to process.
-     * @return The number of 1 bits.
+     *            the long to examine.
+     * @return the number of 1 bits in {@code lng}.
      * @since 1.5
      */
     public static int bitCount(long lng) {
@@ -700,16 +658,14 @@
     }
 
     /**
-     * <p>
-     * Rotates the bits of <code>lng</code> to the left by the
-     * <code>distance</code> bits.
-     * </p>
-     * 
+     * Rotates the bits of the specified long value to the left by the specified
+     * number of bits.
+     *
      * @param lng
-     *            The <code>long</code> value to rotate left.
+     *            the long value to rotate left.
      * @param distance
-     *            The number of bits to rotate.
-     * @return The rotated value.
+     *            the number of bits to rotate.
+     * @return the rotated value.
      * @since 1.5
      */
     public static long rotateLeft(long lng, int distance) {
@@ -726,15 +682,14 @@
 
     /**
      * <p>
-     * Rotates the bits of <code>lng</code> to the right by the
-     * <code>distance</code> bits.
-     * </p>
-     * 
+     * Rotates the bits of the specified long value to the right by the
+     * specified number of bits.
+     *
      * @param lng
-     *            The <code>long</code> value to rotate right.
+     *            the long value to rotate right.
      * @param distance
-     *            The number of bits to rotate.
-     * @return The rotated value.
+     *            the number of bits to rotate.
+     * @return the rotated value.
      * @since 1.5
      */
     public static long rotateRight(long lng, int distance) {
@@ -750,13 +705,11 @@
     }
 
     /**
-     * <p>
-     * Reverses the bytes of a <code>long</code>.
-     * </p>
+     * Reverses the order of the bytes of the specified long value.
      * 
      * @param lng
-     *            The <code>long</code> to reverse.
-     * @return The reversed value.
+     *            the long value for which to reverse the byte order.
+     * @return the reversed value.
      * @since 1.5
      */
     public static long reverseBytes(long lng) {
@@ -772,13 +725,11 @@
     }
 
     /**
-     * <p>
-     * Reverses the bytes of a <code>long</code>.
-     * </p>
+     * Reverses the order of the bits of the specified long value.
      * 
      * @param lng
-     *            The <code>long</code> to reverse.
-     * @return The reversed value.
+     *            the long value for which to reverse the bit order.
+     * @return the reversed value.
      * @since 1.5
      */
     public static long reverse(long lng) {
@@ -793,15 +744,13 @@
     }
 
     /**
-     * <p>
-     * The <code>signum</code> function for <code>long</code> values. This
-     * method returns -1 for negative values, 1 for positive values and 0 for
-     * the value 0.
-     * </p>
+     * Returns the value of the {@code signum} function for the specified long
+     * value.
      * 
      * @param lng
-     *            The <code>long</code> value.
-     * @return -1 if negative, 1 if positive otherwise 0.
+     *            the long value to check.
+     * @return -1 if {@code lng} is negative, 1 if {@code lng} is positive, 0 if
+     *         {@code lng} is zero.
      * @since 1.5
      */
     public static int signum(long lng) {
@@ -809,15 +758,15 @@
     }
 
     /**
+     * Returns a {@code Long} instance for the specified long value.
      * <p>
-     * Returns a <code>Long</code> instance for the <code>long</code> value
-     * passed. This method is preferred over the constructor, as this method may
-     * maintain a cache of instances.
-     * </p>
-     * 
+     * If it is not necessary to get a new {@code Long} instance, it is
+     * recommended to use this method instead of the constructor, since it
+     * maintains a cache of instances which may result in better performance.
+     *
      * @param lng
-     *            The long value.
-     * @return A <code>Long</code> instance.
+     *            the long value to store in the instance.
+     * @return a {@code Long} instance containing {@code lng}.
      * @since 1.5
      */
     public static Long valueOf(long lng) {
@@ -831,7 +780,6 @@
         /**
          * <p>
          * A cache of instances used by {@link Long#valueOf(long)} and auto-boxing.
-         * </p>
          */
         static final Long[] CACHE = new Long[256];
 



Mime
View raw message