harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r770909 [5/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/Math.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Math.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Math.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Math.java Sat May  2 08:09:50 2009
@@ -19,193 +19,336 @@
 
 
 /**
- * Class math provides various floating point support routines and some standard
- * constants.
+ * Class Math provides basic math constants and operations such as trigonometric
+ * functions, hyperbolic functions, exponential, logarithms, etc.
  */
 public final class Math {
 
-	/**
-	 * Standard math constants.
-	 */
-	public static final double E = 2.718281828459045;
+    /**
+     * The double value closest to e, the base of the natural logarithm.
+     */
+    public static final double E = 2.718281828459045;
 
-	public static final double PI = 3.141592653589793;
+    /**
+     * The double value closest to pi, the ratio of a circle's circumference to
+     * its diameter.
+     */
+    public static final double PI = 3.141592653589793;
 
-	private static java.util.Random random;
+    private static java.util.Random random;
 
-	/**
-	 * Prevents this class from being instantiated.
-	 */
-	private Math() {
-	}
+    /**
+     * Prevents this class from being instantiated.
+     */
+    private Math() {
+    }
 
-	/**
-	 * Answers the absolute value of the argument.
-	 * 
-	 * @param d
-	 *            the value to be converted
-	 * @return the argument if it is positive, otherwise the negation of the
-	 *         argument.
-	 */
+    /**
+     * Returns the absolute value of the argument.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code abs(-0.0) = +0.0}</li>
+     * <li>{@code abs(+infinity) = +infinity}</li>
+     * <li>{@code abs(-infinity) = +infinity}</li>
+     * <li>{@code abs(NaN) = NaN}</li>
+     * </ul>
+     *
+     * @param d
+     *            the value whose absolute value has to be computed.
+     * @return the absolute value of the argument.
+     */
 	public static double abs(double d) {
 		long bits = Double.doubleToLongBits(d);
 		bits &= 0x7fffffffffffffffL;
 		return Double.longBitsToDouble(bits);
 	}
 
-	/**
-	 * Answers the absolute value of the argument.
-	 * 
-	 * @param f
-	 *            the value to be converted
-	 * @return the argument if it is positive, otherwise the negation of the
-	 *         argument.
-	 */
+    /**
+     * Returns the absolute value of the argument.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code abs(-0.0) = +0.0}</li>
+     * <li>{@code abs(+infinity) = +infinity}</li>
+     * <li>{@code abs(-infinity) = +infinity}</li>
+     * <li>{@code abs(NaN) = NaN}</li>
+     * </ul>
+     *
+     * @param f
+     *            the value whose absolute value has to be computed.
+     * @return the argument if it is positive, otherwise the negation of the
+     *         argument.
+     */
 	public static float abs(float f) {
 		int bits = Float.floatToIntBits(f);
 		bits &= 0x7fffffff;
 		return Float.intBitsToFloat(bits);
 	}
 
-	/**
-	 * Answers the absolute value of the argument.
-	 * 
-	 * @param i
-	 *            the value to be converted
-	 * @return the argument if it is positive, otherwise the negation of the
-	 *         argument.
-	 */
+    /**
+     * Returns the absolute value of the argument.
+     * <p>
+     * If the argument is {@code Integer.MIN_VALUE}, {@code Integer.MIN_VALUE}
+     * is returned.
+     *
+     * @param i
+     *            the value whose absolute value has to be computed.
+     * @return the argument if it is positive, otherwise the negation of the
+     *         argument.
+     */
 	public static int abs(int i) {
 		return i >= 0 ? i : -i;
 	}
 
-	/**
-	 * Answers the absolute value of the argument.
-	 * 
-	 * @param l
-	 *            the value to be converted
-	 * @return the argument if it is positive, otherwise the negation of the
-	 *         argument.
-	 */
+    /**
+     * Returns the absolute value of the argument. If the argument is {@code
+     * Long.MIN_VALUE}, {@code Long.MIN_VALUE} is returned.
+     *
+     * @param l
+     *            the value whose absolute value has to be computed.
+     * @return the argument if it is positive, otherwise the negation of the
+     *         argument.
+     */
 	public static long abs(long l) {
 		return l >= 0 ? l : -l;
 	}
 
-	/**
-	 * Answers the closest double approximation of the arc cosine of the
-	 * argument
-	 * 
-	 * @param d
-	 *            the value to compute acos of
-	 * @return the arc cosine of the argument.
-	 */
+    /**
+     * Returns the closest double approximation of the arc cosine of the
+     * argument within the range {@code [0..pi]}. The returned result is within
+     * 1 ulp (unit in the last place) of the real result.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code acos((anything > 1) = NaN}</li>
+     * <li>{@code acos((anything < -1) = NaN}</li>
+     * <li>{@code acos(NaN) = NaN}</li>
+     * </ul>
+     *
+     * @param d
+     *            the value to compute arc cosine of.
+     * @return the arc cosine of the argument.
+     */
 	public static native double acos(double d);
 
-	/**
-	 * Answers the closest double approximation of the arc sine of the argument
-	 * 
-	 * @param d
-	 *            the value to compute asin of
-	 * @return the arc sine of the argument.
-	 */
+    /**
+     * Returns the closest double approximation of the arc sine of the argument
+     * within the range {@code [-pi/2..pi/2]}. The returned result is within 1
+     * ulp (unit in the last place) of the real result.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code asin((anything > 1)) = NaN}</li>
+     * <li>{@code asin((anything < -1)) = NaN}</li>
+     * <li>{@code asin(NaN) = NaN}</li>
+     * </ul>
+     *
+     * @param d
+     *            the value whose arc sine has to be computed.
+     * @return the arc sine of the argument.
+     */
 	public static native double asin(double d);
 
-	/**
-	 * Answers the closest double approximation of the arc tangent of the
-	 * argument
-	 * 
-	 * @param d
-	 *            the value to compute atan of
-	 * @return the arc tangent of the argument.
-	 */
-	public static native double atan(double d);
+    /**
+     * Returns the closest double approximation of the arc tangent of the
+     * argument within the range {@code [-pi/2..pi/2]}. The returned result is
+     * within 1 ulp (unit in the last place) of the real result.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code atan(+0.0) = +0.0}</li>
+     * <li>{@code atan(-0.0) = -0.0}</li>
+     * <li>{@code atan(+infinity) = +pi/2}</li>
+     * <li>{@code atan(-infinity) = -pi/2}</li>
+     * <li>{@code atan(NaN) = NaN}</li>
+     * </ul>
+     *
+     * @param d
+     *            the value whose arc tangent has to be computed.
+     * @return the arc tangent of the argument.
+     */
+    public static native double atan(double d);
 
-	/**
-	 * Answers the closest double approximation of the arc tangent of the result
-	 * of dividing the first argument by the second argument.
-	 * 
-	 * @param d1
-	 *            the numerator of the value to compute atan of
-	 * @param d2
-	 *            the denominator of the value to compute atan of
-	 * @return the arc tangent of d1/d2.
-	 */
-	public static native double atan2(double d1, double d2);
+    /**
+     * Returns the closest double approximation of the arc tangent of
+     * {@code y/x} within the range {@code [-pi..pi]}. This is the angle of the
+     * polar representation of the rectangular coordinates (x,y). The returned
+     * result is within 2 ulps (units in the last place) of the real result.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code atan2((anything), NaN ) = NaN;}</li>
+     * <li>{@code atan2(NaN , (anything) ) = NaN;}</li>
+     * <li>{@code atan2(+0.0, +(anything but NaN)) = +0.0}</li>
+     * <li>{@code atan2(-0.0, +(anything but NaN)) = -0.0}</li>
+     * <li>{@code atan2(+0.0, -(anything but NaN)) = +pi}</li>
+     * <li>{@code atan2(-0.0, -(anything but NaN)) = -pi}</li>
+     * <li>{@code atan2(+(anything but 0 and NaN), 0) = +pi/2}</li>
+     * <li>{@code atan2(-(anything but 0 and NaN), 0) = -pi/2}</li>
+     * <li>{@code atan2(+(anything but infinity and NaN), +infinity)} {@code =}
+     * {@code +0.0}</li>
+     * <li>{@code atan2(-(anything but infinity and NaN), +infinity)} {@code =}
+     * {@code -0.0}</li>
+     * <li>{@code atan2(+(anything but infinity and NaN), -infinity) = +pi}</li>
+     * <li>{@code atan2(-(anything but infinity and NaN), -infinity) = -pi}</li>
+     * <li>{@code atan2(+infinity, +infinity ) = +pi/4}</li>
+     * <li>{@code atan2(-infinity, +infinity ) = -pi/4}</li>
+     * <li>{@code atan2(+infinity, -infinity ) = +3pi/4}</li>
+     * <li>{@code atan2(-infinity, -infinity ) = -3pi/4}</li>
+     * <li>{@code atan2(+infinity, (anything but,0, NaN, and infinity))}
+     * {@code =} {@code +pi/2}</li>
+     * <li>{@code atan2(-infinity, (anything but,0, NaN, and infinity))}
+     * {@code =} {@code -pi/2}</li>
+     * </ul>
+     *
+     * @param y
+     *            the numerator of the value whose atan has to be computed.
+     * @param x
+     *            the denominator of the value whose atan has to be computed.
+     * @return the arc tangent of {@code y/x}.
+     */
+    public static native double atan2(double x, double y);
     
     /**
-     * Answers the closest double approximation of the cube root of the
-     * argument. The final result should be within 1ulp of the real result.
-     * 
+     * Returns the closest double approximation of the cube root of the
+     * argument.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code cbrt(+0.0) = +0.0}</li>
+     * <li>{@code cbrt(-0.0) = -0.0}</li>
+     * <li>{@code cbrt(+infinity) = +infinity}</li>
+     * <li>{@code cbrt(-infinity) = -infinity}</li>
+     * <li>{@code cbrt(NaN) = NaN}</li>
+     * </ul>
+     *
      * @param d
-     *            the value to compute cube root of
+     *            the value whose cube root has to be computed.
      * @return the cube root of the argument.
      */
     public static native double cbrt(double d);
 
-	/**
-	 * Answers the double conversion of the most negative (i.e. closest to
-	 * negative infinity) integer value which is greater than the argument.
-	 * 
-	 * @param d
-	 *            the value to be converted
-	 * @return the ceiling of the argument.
-	 */
+    /**
+     * Returns the double conversion of the most negative (closest to
+     * negative infinity) integer value which is greater than the argument.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code ceil(+0.0) = +0.0}</li>
+     * <li>{@code ceil(-0.0) = -0.0}</li>
+     * <li>{@code ceil((anything in range (-1,0)) = -0.0}</li>
+     * <li>{@code ceil(+infinity) = +infinity}</li>
+     * <li>{@code ceil(-infinity) = -infinity}</li>
+     * <li>{@code ceil(NaN) = NaN}</li>
+     * </ul>
+     *
+     * @param d
+     *            the value whose closest integer value has to be computed.
+     * @return the ceiling of the argument.
+     */
 	public static double ceil(double d) {
             return -floor(-d);
         } 
 
 	/**
-	 * Answers the closest double approximation of the cosine of the argument
-	 * 
-	 * @param d
-	 *            the value to compute cos of
-	 * @return the cosine of the argument.
-	 */
-	public static native double cos(double d);
+     * Returns the closest double approximation of the cosine of the argument.
+     * The returned result is within 1 ulp (unit in the last place) of the real
+     * result.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code cos(+infinity) = NaN}</li>
+     * <li>{@code cos(-infinity) = NaN}</li>
+     * <li>{@code cos(NaN) = NaN}</li>
+     * </ul>
+     *
+     * @param d
+     *            the angle whose cosine has to be computed, in radians.
+     * @return the cosine of the argument.
+     */
+    public static native double cos(double d);
     
     /**
-     * Answers the closest double approximation of the hyperbolic cosine of the
-     * argument. The final result should be within 2.5ulps of the real result.
-     * 
+     * Returns the closest double approximation of the hyperbolic cosine of the
+     * argument. The returned result is within 2.5 ulps (units in the last
+     * place) of the real result.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code cosh(+infinity) = +infinity}</li>
+     * <li>{@code cosh(-infinity) = +infinity}</li>
+     * <li>{@code cosh(NaN) = NaN}</li>
+     * </ul>
+     *
      * @param d
-     *            the value to compute hyperbolic cosine of
+     *            the value whose hyperbolic cosine has to be computed.
      * @return the hyperbolic cosine of the argument.
      */
     public static native double cosh(double d);
 
-	/**
-	 * Answers the closest double approximation of the raising "e" to the power
-	 * of the argument
-	 * 
-	 * @param d
-	 *            the value to compute the exponential of
-	 * @return the exponential of the argument.
-	 */
-	public static native double exp(double d);
+    /**
+     * Returns the closest double approximation of the raising "e" to the power
+     * of the argument. The returned result is within 1 ulp (unit in the last
+     * place) of the real result.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code exp(+infinity) = +infinity}</li>
+     * <li>{@code exp(-infinity) = +0.0}</li>
+     * <li>{@code exp(NaN) = NaN}</li>
+     * </ul>
+     *
+     * @param d
+     *            the value whose exponential has to be computed.
+     * @return the exponential of the argument.
+     */
+    public static native double exp(double d);
     
     /**
-     * Answers the closest double approximation of <i>e</i><sup>d</sup> - 1.
-     * If the argument is very close to 0, it is much more accurate to use
-     * expm1(d)+1 than exp(d).
-     * 
-     * The final result should be within 1 ulp of the real result. For any
-     * finite input, the result should be no less than -1.0. If the real result
-     * is within 0.5 ulp of -1, -1.0 should be answered.
-     * 
+     * Returns the closest double approximation of <i>{@code e}</i><sup>
+     * {@code d}</sup>{@code - 1}. If the argument is very close to 0, it is
+     * much more accurate to use {@code expm1(d)+1} than {@code exp(d)} (due to
+     * cancellation of significant digits). The returned result is within 1 ulp
+     * (unit in the last place) of the real result.
+     * <p>
+     * For any finite input, the result is not less than -1.0. If the real
+     * result is within 0.5 ulp of -1, -1.0 is returned.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code expm1(+0.0) = +0.0}</li>
+     * <li>{@code expm1(-0.0) = -0.0}</li>
+     * <li>{@code expm1(+infinity) = +infinity}</li>
+     * <li>{@code expm1(-infinity) = -1.0}</li>
+     * <li>{@code expm1(NaN) = NaN}</li>
+     * </ul>
+     *
      * @param d
-     *            the value to compute the <i>e</i><sup>d</sup> - 1 of
-     * @return the <i>e</i><sup>d</sup> - 1 value of the argument.
+     *            the value to compute the <i>{@code e}</i><sup>{@code d}
+     *            </sup>{@code - 1} of.
+     * @return the <i>{@code e}</i><sup>{@code d}</sup>{@code - 1} value
+     *         of the argument.
      */
     public static native double expm1(double d);
 
-	/**
-	 * Answers the double conversion of the most positive (i.e. closest to
-	 * positive infinity) integer value which is less than the argument.
-	 * 
-	 * @param d
-	 *            the value to be converted
-	 * @return the ceiling of the argument.
-	 */
+    /**
+     * Returns the double conversion of the most positive (closest to positive
+     * infinity) integer value which is less than the argument.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code floor(+0.0) = +0.0}</li>
+     * <li>{@code floor(-0.0) = -0.0}</li>
+     * <li>{@code floor(+infinity) = +infinity}</li>
+     * <li>{@code floor(-infinity) = -infinity}</li>
+     * <li>{@code floor(NaN) = NaN}</li>
+     * </ul>
+     *
+     * @param d
+     *            the value whose closest integer value has to be computed.
+     * @return the floor of the argument.
+     */
 	public static double floor(double d) {
             if (Double.isNaN(d) || Double.isInfinite(d) || d == 0) {
                return d; 
@@ -215,77 +358,142 @@
         }
     
     /**
-     * Answers sqrt(<i>x</i><sup>2</sup>+<i>y</i><sup>2</sup>). The
-     * final result is without medium underflow or overflow.
-     * 
-     * The final result should be within 1 ulp of the real result. If one
-     * parameter remains constant, the result should be semi-monotonic.
-     * 
+     * Returns {@code sqrt(}<i>{@code x}</i><sup>{@code 2}</sup>{@code +}
+     * <i> {@code y}</i><sup>{@code 2}</sup>{@code )}. The final result is
+     * without medium underflow or overflow. The returned result is within 1 ulp
+     * (unit in the last place) of the real result. If one parameter remains
+     * constant, the result should be semi-monotonic.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code hypot(+infinity, (anything including NaN)) = +infinity}</li>
+     * <li>{@code hypot(-infinity, (anything including NaN)) = +infinity}</li>
+     * <li>{@code hypot((anything including NaN), +infinity) = +infinity}</li>
+     * <li>{@code hypot((anything including NaN), -infinity) = +infinity}</li>
+     * <li>{@code hypot(NaN, NaN) = NaN}</li>
+     * </ul>
+     *
      * @param x
-     *            a double number
+     *            a double number.
      * @param y
-     *            a double number
-     * @return the sqrt(<i>x</i><sup>2</sup>+<i>y</i><sup>2</sup>) value
-     *         of the arguments.
+     *            a double number.
+     * @return the {@code sqrt(}<i>{@code x}</i><sup>{@code 2}</sup>{@code +}
+     *         <i> {@code y}</i><sup>{@code 2}</sup>{@code )} value of the
+     *         arguments.
      */
     public static native double hypot(double x, double y);
 
-	/**
-	 * Answers the remainder of dividing the first argument by the second using
-	 * the IEEE 754 rules.
-	 * 
-	 * @param d1
-	 *            the numerator of the operation
-	 * @param d2
-	 *            the denominator of the operation
-	 * @return the result of d1/d2.
-	 */
-	public static native double IEEEremainder(double d1, double d2);
+    /**
+     * Returns the remainder of dividing {@code x} by {@code y} using the IEEE
+     * 754 rules. The result is {@code x-round(x/p)*p} where {@code round(x/p)}
+     * is the nearest integer (rounded to even), but without numerical
+     * cancellation problems.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code IEEEremainder((anything), 0) = NaN}</li>
+     * <li>{@code IEEEremainder(+infinity, (anything)) = NaN}</li>
+     * <li>{@code IEEEremainder(-infinity, (anything)) = NaN}</li>
+     * <li>{@code IEEEremainder(NaN, (anything)) = NaN}</li>
+     * <li>{@code IEEEremainder((anything), NaN) = NaN}</li>
+     * <li>{@code IEEEremainder(x, +infinity) = x } where x is anything but
+     * +/-infinity</li>
+     * <li>{@code IEEEremainder(x, -infinity) = x } where x is anything but
+     * +/-infinity</li>
+     * </ul>
+     *
+     * @param x
+     *            the numerator of the operation.
+     * @param y
+     *            the denominator of the operation.
+     * @return the IEEE754 floating point reminder of of {@code x/y}.
+     */
+    public static native double IEEEremainder(double x, double y);
 
-	/**
-	 * Answers the closest double approximation of the natural logarithm of the
-	 * argument
-	 * 
-	 * @param d
-	 *            the value to compute the log of
-	 * @return the natural logarithm of the argument.
-	 */
-	public static native double log(double d);
+    /**
+     * Returns the closest double approximation of the natural logarithm of the
+     * argument. The returned result is within 1 ulp (unit in the last place) of
+     * the real result.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code log(+0.0) = -infinity}</li>
+     * <li>{@code log(-0.0) = -infinity}</li>
+     * <li>{@code log((anything < 0) = NaN}</li>
+     * <li>{@code log(+infinity) = +infinity}</li>
+     * <li>{@code log(-infinity) = NaN}</li>
+     * <li>{@code log(NaN) = NaN}</li>
+     * </ul>
+     *
+     * @param d
+     *            the value whose log has to be computed.
+     * @return the natural logarithm of the argument.
+     */
+    public static native double log(double d);
 
     /**
-     * Answers the closest double approximation of the base 10 logarithm of the
-     * argument
-     * 
+     * Returns the closest double approximation of the base 10 logarithm of the
+     * argument. The returned result is within 1 ulp (unit in the last place) of
+     * the real result.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code log10(+0.0) = -infinity}</li>
+     * <li>{@code log10(-0.0) = -infinity}</li>
+     * <li>{@code log10((anything < 0) = NaN}</li>
+     * <li>{@code log10(+infinity) = +infinity}</li>
+     * <li>{@code log10(-infinity) = NaN}</li>
+     * <li>{@code log10(NaN) = NaN}</li>
+     * </ul>
+     *
      * @param d
-     *            the value to compute the log10 of
+     *            the value whose base 10 log has to be computed.
      * @return the natural logarithm of the argument.
      */
     public static native double log10(double d);
     
     /**
-     * Answers the closest double approximation of the natural logarithm of the
+     * Returns the closest double approximation of the natural logarithm of the
      * sum of the argument and 1. If the argument is very close to 0, it is much
-     * more accurate to use log1p(d) than log(1.0+d).
-     * 
-     * The final result should be within 1 ulp of the real result and be
-     * semi-monotonic.
-     * 
+     * more accurate to use {@code log1p(d)} than {@code log(1.0+d)} (due to
+     * numerical cancellation). The returned result is within 1 ulp (unit in the
+     * last place) of the real result and is semi-monotonic.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code log1p(+0.0) = +0.0}</li>
+     * <li>{@code log1p(-0.0) = -0.0}</li>
+     * <li>{@code log1p((anything < 1)) = NaN}</li>
+     * <li>{@code log1p(-1.0) = -infinity}</li>
+     * <li>{@code log1p(+infinity) = +infinity}</li>
+     * <li>{@code log1p(-infinity) = NaN}</li>
+     * <li>{@code log1p(NaN) = NaN}</li>
+     * </ul>
+     *
      * @param d
-     *            the value to compute the ln(1+d) of
+     *            the value to compute the {@code ln(1+d)} of.
      * @return the natural logarithm of the sum of the argument and 1.
      */
     public static native double log1p(double d);
 
-	/**
-	 * Answers the most positive (i.e. closest to positive infinity) of the two
-	 * arguments.
-	 * 
-	 * @param d1
-	 *            the first argument to check
-	 * @param d2
-	 *            the second argument
-	 * @return the larger of d1 and d2.
-	 */
+    /**
+     * Returns the most positive (closest to positive infinity) of the two
+     * arguments.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code max(NaN, (anything)) = NaN}</li>
+     * <li>{@code max((anything), NaN) = NaN}</li>
+     * <li>{@code max(+0.0, -0.0) = +0.0}</li>
+     * <li>{@code max(-0.0, +0.0) = +0.0}</li>
+     * </ul>
+     *
+     * @param d1
+     *            the first argument.
+     * @param d2
+     *            the second argument.
+     * @return the larger of {@code d1} and {@code d2}.
+     */
 	public static double max(double d1, double d2) {
 		if (d1 > d2)
 			return d1;
@@ -300,16 +508,24 @@
 		return d1;
 	}
 
-	/**
-	 * Answers the most positive (i.e. closest to positive infinity) of the two
-	 * arguments.
-	 * 
-	 * @param f1
-	 *            the first argument to check
-	 * @param f2
-	 *            the second argument
-	 * @return the larger of f1 and f2.
-	 */
+    /**
+     * Returns the most positive (closest to positive infinity) of the two
+     * arguments.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code max(NaN, (anything)) = NaN}</li>
+     * <li>{@code max((anything), NaN) = NaN}</li>
+     * <li>{@code max(+0.0, -0.0) = +0.0}</li>
+     * <li>{@code max(-0.0, +0.0) = +0.0}</li>
+     * </ul>
+     *
+     * @param f1
+     *            the first argument.
+     * @param f2
+     *            the second argument.
+     * @return the larger of {@code f1} and {@code f2}.
+     */
 	public static float max(float f1, float f2) {
 		if (f1 > f2)
 			return f1;
@@ -324,44 +540,52 @@
 		return f1;
 	}
 
-	/**
-	 * Answers the most positive (i.e. closest to positive infinity) of the two
-	 * arguments.
-	 * 
-	 * @param i1
-	 *            the first argument to check
-	 * @param i2
-	 *            the second argument
-	 * @return the larger of i1 and i2.
-	 */
+    /**
+     * Returns the most positive (closest to positive infinity) of the two
+     * arguments.
+     *
+     * @param i1
+     *            the first argument.
+     * @param i2
+     *            the second argument.
+     * @return the larger of {@code i1} and {@code i2}.
+     */
 	public static int max(int i1, int i2) {
 		return i1 > i2 ? i1 : i2;
 	}
 
-	/**
-	 * Answers the most positive (i.e. closest to positive infinity) of the two
-	 * arguments.
-	 * 
-	 * @param l1
-	 *            the first argument to check
-	 * @param l2
-	 *            the second argument
-	 * @return the larger of l1 and l2.
-	 */
+    /**
+     * Returns the most positive (closest to positive infinity) of the two
+     * arguments.
+     *
+     * @param l1
+     *            the first argument.
+     * @param l2
+     *            the second argument.
+     * @return the larger of {@code l1} and {@code l2}.
+     */
 	public static long max(long l1, long l2) {
 		return l1 > l2 ? l1 : l2;
 	}
 
-	/**
-	 * Answers the most negative (i.e. closest to negative infinity) of the two
-	 * arguments.
-	 * 
-	 * @param d1
-	 *            the first argument to check
-	 * @param d2
-	 *            the second argument
-	 * @return the smaller of d1 and d2.
-	 */
+    /**
+     * Returns the most negative (closest to negative infinity) of the two
+     * arguments.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code min(NaN, (anything)) = NaN}</li>
+     * <li>{@code min((anything), NaN) = NaN}</li>
+     * <li>{@code min(+0.0, -0.0) = -0.0}</li>
+     * <li>{@code min(-0.0, +0.0) = -0.0}</li>
+     * </ul>
+     *
+     * @param d1
+     *            the first argument.
+     * @param d2
+     *            the second argument.
+     * @return the smaller of {@code d1} and {@code d2}.
+     */
 	public static double min(double d1, double d2) {
 		if (d1 > d2)
 			return d2;
@@ -376,16 +600,24 @@
 		return d1;
 	}
 
-	/**
-	 * Answers the most negative (i.e. closest to negative infinity) of the two
-	 * arguments.
-	 * 
-	 * @param f1
-	 *            the first argument to check
-	 * @param f2
-	 *            the second argument
-	 * @return the smaller of f1 and f2.
-	 */
+    /**
+     * Returns the most negative (closest to negative infinity) of the two
+     * arguments.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code min(NaN, (anything)) = NaN}</li>
+     * <li>{@code min((anything), NaN) = NaN}</li>
+     * <li>{@code min(+0.0, -0.0) = -0.0}</li>
+     * <li>{@code min(-0.0, +0.0) = -0.0}</li>
+     * </ul>
+     *
+     * @param f1
+     *            the first argument.
+     * @param f2
+     *            the second argument.
+     * @return the smaller of {@code f1} and {@code f2}.
+     */
 	public static float min(float f1, float f2) {
 		if (f1 > f2)
 			return f2;
@@ -400,54 +632,90 @@
 		return f1;
 	}
 
-	/**
-	 * Answers the most negative (i.e. closest to negative infinity) of the two
-	 * arguments.
-	 * 
-	 * @param i1
-	 *            the first argument to check
-	 * @param i2
-	 *            the second argument
-	 * @return the smaller of i1 and i2.
-	 */
+    /**
+     * Returns the most negative (closest to negative infinity) of the two
+     * arguments.
+     *
+     * @param i1
+     *            the first argument.
+     * @param i2
+     *            the second argument.
+     * @return the smaller of {@code i1} and {@code i2}.
+     */
 	public static int min(int i1, int i2) {
 		return i1 < i2 ? i1 : i2;
 	}
 
-	/**
-	 * Answers the most negative (i.e. closest to negative infinity) of the two
-	 * arguments.
-	 * 
-	 * @param l1
-	 *            the first argument to check
-	 * @param l2
-	 *            the second argument
-	 * @return the smaller of l1 and l2.
-	 */
+    /**
+     * Returns the most negative (closest to negative infinity) of the two
+     * arguments.
+     *
+     * @param l1
+     *            the first argument.
+     * @param l2
+     *            the second argument.
+     * @return the smaller of {@code l1} and {@code l2}.
+     */
 	public static long min(long l1, long l2) {
 		return l1 < l2 ? l1 : l2;
 	}
 
-	/**
-	 * Answers the closest double approximation of the result of raising the
-	 * first argument to the power of the second.
-	 * 
-	 * @param d1
-	 *            the base of the operation.
-	 * @param d2
-	 *            the exponent of the operation.
-	 * @return d1 to the power of d2
-	 */
-	public static native double pow(double d1, double d2);
+    /**
+     * Returns the closest double approximation of the result of raising
+     * {@code x} to the power of {@code y}.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code pow((anything), +0.0) = 1.0}</li>
+     * <li>{@code pow((anything), -0.0) = 1.0}</li>
+     * <li>{@code pow(x, 1.0) = x}</li>
+     * <li>{@code pow((anything), NaN) = NaN}</li>
+     * <li>{@code pow(NaN, (anything except 0)) = NaN}</li>
+     * <li>{@code pow(+/-(|x| > 1), +infinity) = +infinity}</li>
+     * <li>{@code pow(+/-(|x| > 1), -infinity) = +0.0}</li>
+     * <li>{@code pow(+/-(|x| < 1), +infinity) = +0.0}</li>
+     * <li>{@code pow(+/-(|x| < 1), -infinity) = +infinity}</li>
+     * <li>{@code pow(+/-1.0 , +infinity) = NaN}</li>
+     * <li>{@code pow(+/-1.0 , -infinity) = NaN}</li>
+     * <li>{@code pow(+0.0, (+anything except 0, NaN)) = +0.0}</li>
+     * <li>{@code pow(-0.0, (+anything except 0, NaN, odd integer)) = +0.0}</li>
+     * <li>{@code pow(+0.0, (-anything except 0, NaN)) = +infinity}</li>
+     * <li>{@code pow(-0.0, (-anything except 0, NAN, odd integer))} {@code =}
+     * {@code +infinity}</li>
+     * <li>{@code pow(-0.0, (odd integer)) = -pow( +0 , (odd integer) )}</li>
+     * <li>{@code pow(+infinity, (+anything except 0, NaN)) = +infinity}</li>
+     * <li>{@code pow(+infinity, (-anything except 0, NaN)) = +0.0}</li>
+     * <li>{@code pow(-infinity, (anything)) = -pow(0, (-anything))}</li>
+     * <li>{@code pow((-anything), (integer))} {@code =}
+     * {@code pow(-1,(integer))*pow(+anything,integer) }</li>
+     * <li>{@code pow((-anything except 0 and inf), (non-integer)) = NAN}</li>
+     * </ul>
+     *
+     * @param x
+     *            the base of the operation.
+     * @param y
+     *            the exponent of the operation.
+     * @return {@code x} to the power of {@code y}.
+     */
+    public static native double pow(double x, double y);
 
-	/**
-	 * Answers the double conversion of the result of rounding the argument to
-	 * an integer.
-	 * 
-	 * @param d
-	 *            the value to be converted
-	 * @return the closest integer to the argument (as a double).
-	 */
+    /**
+     * Returns the double conversion of the result of rounding the argument to
+     * an integer. Tie breaks are rounded towards even.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code rint(+0.0) = +0.0}</li>
+     * <li>{@code rint(-0.0) = -0.0}</li>
+     * <li>{@code rint(+infinity) = +infinity}</li>
+     * <li>{@code rint(-infinity) = -infinity}</li>
+     * <li>{@code rint(NaN) = NaN}</li>
+     * </ul>
+     *
+     * @param d
+     *            the value to be rounded.
+     * @return the closest integer to the argument (as a double).
+     */
 	public static double rint(double d) {
 	    if(d == +0.0d || d == -0.0d) {
 	        return d;
@@ -457,12 +725,24 @@
         }
 
 	/**
-	 * Answers the result of rounding the argument to an integer.
-	 * 
-	 * @param d
-	 *            the value to be converted
-	 * @return the closest integer to the argument.
-	 */
+     * Returns the result of rounding the argument to an integer. The result is
+     * equivalent to {@code (long) Math.floor(d+0.5)}.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code round(+0.0) = +0.0}</li>
+     * <li>{@code round(-0.0) = +0.0}</li>
+     * <li>{@code round((anything > Long.MAX_VALUE) = Long.MAX_VALUE}</li>
+     * <li>{@code round((anything < Long.MIN_VALUE) = Long.MIN_VALUE}</li>
+     * <li>{@code round(+infintiy) = Long.MAX_VALUE}</li>
+     * <li>{@code round(-infintiy) = Long.MIN_VALUE}</li>
+     * <li>{@code round(NaN) = +0.0}</li>
+     * </ul>
+     *
+     * @param d
+     *            the value to be rounded.
+     * @return the closest integer to the argument.
+     */
 	public static long round(double d) {
 		// check for NaN
 		if (d != d)
@@ -470,13 +750,25 @@
 		return (long) floor(d + 0.5d);
 	}
 
-	/**
-	 * Answers the result of rounding the argument to an integer.
-	 * 
-	 * @param f
-	 *            the value to be converted
-	 * @return the closest integer to the argument.
-	 */
+    /**
+     * Returns the result of rounding the argument to an integer. The result is
+     * equivalent to {@code (int) Math.floor(f+0.5)}.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code round(+0.0) = +0.0}</li>
+     * <li>{@code round(-0.0) = +0.0}</li>
+     * <li>{@code round((anything > Integer.MAX_VALUE) = Integer.MAX_VALUE}</li>
+     * <li>{@code round((anything < Integer.MIN_VALUE) = Integer.MIN_VALUE}</li>
+     * <li>{@code round(+infintiy) = Integer.MAX_VALUE}</li>
+     * <li>{@code round(-infintiy) = Integer.MIN_VALUE}</li>
+     * <li>{@code round(NaN) = +0.0}</li>
+     * </ul>
+     *
+     * @param f
+     *            the value to be rounded.
+     * @return the closest integer to the argument.
+     */
 	public static int round(float f) {
 		// check for NaN
 		if (f != f)
@@ -485,12 +777,22 @@
 	}
     
     /**
-     * Answers the signum function of the argument. If the argument is less than
-     * zero, it answers -1.0. If greater than zero, 1.0 is returned. It returns
-     * zero if the argument is also zero.
-     * 
+     * Returns the signum function of the argument. If the argument is less than
+     * zero, it returns -1.0. If the argument is greater than zero, 1.0 is
+     * returned. If the argument is either positive or negative zero, the
+     * argument is returned as result.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code signum(+0.0) = +0.0}</li>
+     * <li>{@code signum(-0.0) = -0.0}</li>
+     * <li>{@code signum(+infinity) = +1.0}</li>
+     * <li>{@code signum(-infinity) = -1.0}</li>
+     * <li>{@code signum(NaN) = NaN}</li>
+     * </ul>
+     *
      * @param d
-     *            the value to compute signum function of
+     *            the value whose signum has to be computed.
      * @return the value of the signum function.
      */
     public static double signum(double d) {
@@ -498,73 +800,135 @@
     }
     
     /**
-     * Answers the signum function of the argument. If the argument is less than
-     * zero, it answers -1.0. If greater than zero, 1.0 is returned. It returns
-     * zero if the argument is also zero.
-     * 
+     * Returns the signum function of the argument. If the argument is less than
+     * zero, it returns -1.0. If the argument is greater than zero, 1.0 is
+     * returned. If the argument is either positive or negative zero, the
+     * argument is returned as result.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code signum(+0.0) = +0.0}</li>
+     * <li>{@code signum(-0.0) = -0.0}</li>
+     * <li>{@code signum(+infinity) = +1.0}</li>
+     * <li>{@code signum(-infinity) = -1.0}</li>
+     * <li>{@code signum(NaN) = NaN}</li>
+     * </ul>
+     *
      * @param f
-     *            the value to compute signum function of
+     *            the value whose signum has to be computed.
      * @return the value of the signum function.
      */
     public static float signum(float f) {
         return StrictMath.signum(f);
     }
 
-	/**
-	 * Answers the closest double approximation of the sine of the argument
-	 * 
-	 * @param d
-	 *            the value to compute sin of
-	 * @return the sine of the argument.
-	 */
-	public static native double sin(double d);
+    /**
+     * Returns the closest double approximation of the sine of the argument. The
+     * returned result is within 1 ulp (unit in the last place) of the real
+     * result.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code sin(+0.0) = +0.0}</li>
+     * <li>{@code sin(-0.0) = -0.0}</li>
+     * <li>{@code sin(+infinity) = NaN}</li>
+     * <li>{@code sin(-infinity) = NaN}</li>
+     * <li>{@code sin(NaN) = NaN}</li>
+     * </ul>
+     *
+     * @param d
+     *            the angle whose sin has to be computed, in radians.
+     * @return the sine of the argument.
+     */
+    public static native double sin(double d);
     
     /**
-     * Answers the closest double approximation of the hyperbolic sine of the
-     * argument. The final result should be within 2.5ulps of the real result.
-     * 
+     * Returns the closest double approximation of the hyperbolic sine of the
+     * argument. The returned result is within 2.5 ulps (units in the last
+     * place) of the real result.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code sinh(+0.0) = +0.0}</li>
+     * <li>{@code sinh(-0.0) = -0.0}</li>
+     * <li>{@code sinh(+infinity) = +infinity}</li>
+     * <li>{@code sinh(-infinity) = -infinity}</li>
+     * <li>{@code sinh(NaN) = NaN}</li>
+     * </ul>
+     *
      * @param d
-     *            the value to compute hyperbolic sine of
+     *            the value whose hyperbolic sine has to be computed.
      * @return the hyperbolic sine of the argument.
      */
     public static native double sinh(double d);
 
-	/**
-	 * Answers the closest double approximation of the square root of the
-	 * argument
-	 * 
-	 * @param d
-	 *            the value to compute sqrt of
-	 * @return the square root of the argument.
-	 */
-	public static native double sqrt(double d);
+    /**
+     * Returns the closest double approximation of the square root of the
+     * argument.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code sqrt(+0.0) = +0.0}</li>
+     * <li>{@code sqrt(-0.0) = -0.0}</li>
+     * <li>{@code sqrt( (anything < 0) ) = NaN}</li>
+     * <li>{@code sqrt(+infinity) = +infinity}</li>
+     * <li>{@code sqrt(NaN) = NaN}</li>
+     * </ul>
+     *
+     * @param d
+     *            the value whose square root has to be computed.
+     * @return the square root of the argument.
+     */
+    public static native double sqrt(double d);
 
-	/**
-	 * Answers the closest double approximation of the tangent of the argument
-	 * 
-	 * @param d
-	 *            the value to compute tan of
-	 * @return the tangent of the argument.
-	 */
-	public static native double tan(double d);
+    /**
+     * Returns the closest double approximation of the tangent of the argument.
+     * The returned result is within 1 ulp (unit in the last place) of the real
+     * result.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code tan(+0.0) = +0.0}</li>
+     * <li>{@code tan(-0.0) = -0.0}</li>
+     * <li>{@code tan(+infinity) = NaN}</li>
+     * <li>{@code tan(-infinity) = NaN}</li>
+     * <li>{@code tan(NaN) = NaN}</li>
+     * </ul>
+     *
+     * @param d
+     *            the angle whose tangens has to be computed, in radians.
+     * @return the tangent of the argument.
+     */
+    public static native double tan(double d);
     
     /**
-     * Answers the closest double approximation of the hyperbolic tangent of the
-     * argument. The absolute value is always less than 1. The final result
-     * should be within 2.5ulps of the real result. If the real result is 
-     * within 0.5ulp of 1 or -1, it should answer exactly +1 or -1.
-     * 
+     * Returns the closest double approximation of the hyperbolic tangent of the
+     * argument. The absolute value is always less than 1. The returned result
+     * is within 2.5 ulps (units in the last place) of the real result. If the
+     * real result is within 0.5ulp of 1 or -1, it should return exactly +1 or
+     * -1.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code tanh(+0.0) = +0.0}</li>
+     * <li>{@code tanh(-0.0) = -0.0}</li>
+     * <li>{@code tanh(+infinity) = +1.0}</li>
+     * <li>{@code tanh(-infinity) = -1.0}</li>
+     * <li>{@code tanh(NaN) = NaN}</li>
+     * </ul>
+     *
      * @param d
-     *            the value to compute hyperbolic tangent of
+     *            the value whose hyperbolic tangent has to be computed.
      * @return the hyperbolic tangent of the argument.
      */
     public static native double tanh(double d);
 
-	/**
-	 * Returns a pseudo-random number between 0.0 and 1.0.
-	 * 
-	 * @return a pseudo-random number
-	 */
+    /**
+     * Returns a pseudo-random number between 0.0 (inclusive) and 1.0
+     * (exclusive).
+     *
+     * @return a pseudo-random number.
+     */
 	public static double random() {
 		if (random == null) {
 			random = new java.util.Random();
@@ -572,35 +936,65 @@
 		return random.nextDouble();
 	}
 
-	/**
-	 * Returns the measure in radians of the supplied degree angle
-	 * 
-	 * @param angdeg
-	 *            an angle in degrees
-	 * @return the radian measure of the angle.
-	 */
+    /**
+     * Returns the measure in radians of the supplied degree angle. The result
+     * is {@code angdeg / 180 * pi}.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code toRadians(+0.0) = +0.0}</li>
+     * <li>{@code toRadians(-0.0) = -0.0}</li>
+     * <li>{@code toRadians(+infinity) = +infinity}</li>
+     * <li>{@code toRadians(-infinity) = -infinity}</li>
+     * <li>{@code toRadians(NaN) = NaN}</li>
+     * </ul>
+     *
+     * @param angdeg
+     *            an angle in degrees.
+     * @return the radian measure of the angle.
+     */
 	public static double toRadians(double angdeg) {
 		return angdeg / 180d * PI;
 	}
 
-	/**
-	 * Returns the measure in degrees of the supplied radian angle
-	 * 
-	 * @param angrad
-	 *            an angle in radians
-	 * @return the degree measure of the angle.
-	 */
+    /**
+     * Returns the measure in degrees of the supplied radian angle. The result
+     * is {@code angrad * 180 / pi}.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code toDegrees(+0.0) = +0.0}</li>
+     * <li>{@code toDegrees(-0.0) = -0.0}</li>
+     * <li>{@code toDegrees(+infinity) = +infinity}</li>
+     * <li>{@code toDegrees(-infinity) = -infinity}</li>
+     * <li>{@code toDegrees(NaN) = NaN}</li>
+     * </ul>
+     *
+     * @param angrad
+     *            an angle in radians.
+     * @return the degree measure of the angle.
+     */
 	public static double toDegrees(double angrad) {
 		return angrad * 180d / PI;
 	}
 	
 	/**
-     * Answers the argument's ulp. The size of a ulp of a double value is the
-     * positive distance between this value and the double value next larger
-     * in magnitude. For non-NaN x, ulp(-x) == ulp(x).
-     * 
+     * Returns the argument's ulp (unit in the last place). The size of a ulp of
+     * a double value is the positive distance between this value and the double
+     * value next larger in magnitude. For non-NaN {@code x},
+     * {@code ulp(-x) == ulp(x)}.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code ulp(+0.0) = Double.MIN_VALUE}</li>
+     * <li>{@code ulp(-0.0) = Double.MIN_VALUE}</li>
+     * <li>{@code ulp(+infintiy) = infinity}</li>
+     * <li>{@code ulp(-infintiy) = infinity}</li>
+     * <li>{@code ulp(NaN) = NaN}</li>
+     * </ul>
+     *
      * @param d
-     *            the floating-point value to compute ulp of
+     *            the floating-point value to compute ulp of.
      * @return the size of a ulp of the argument.
      */
     public static double ulp(double d) {
@@ -615,12 +1009,22 @@
     }
 
     /**
-     * Answers the argument's ulp. The size of a ulp of a float value is the
-     * positive distance between this value and the float value next larger
-     * in magnitude. For non-NaN x, ulp(-x) == ulp(x).
-     * 
+     * Returns the argument's ulp (unit in the last place). The size of a ulp of
+     * a float value is the positive distance between this value and the float
+     * value next larger in magnitude. For non-NaN {@code x},
+     * {@code ulp(-x) == ulp(x)}.
+     * <p>
+     * Special cases:
+     * <ul>
+     * <li>{@code ulp(+0.0) = Float.MIN_VALUE}</li>
+     * <li>{@code ulp(-0.0) = Float.MIN_VALUE}</li>
+     * <li>{@code ulp(+infintiy) = infinity}</li>
+     * <li>{@code ulp(-infintiy) = infinity}</li>
+     * <li>{@code ulp(NaN) = NaN}</li>
+     * </ul>
+     *
      * @param f
-     *            the floating-point value to compute ulp of
+     *            the floating-point value to compute ulp of.
      * @return the size of a ulp of the argument.
      */
     public static float ulp(float f) {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NegativeArraySizeException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NegativeArraySizeException.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NegativeArraySizeException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NegativeArraySizeException.java Sat May  2 08:09:50 2009
@@ -17,30 +17,30 @@
 
 package java.lang;
 
-
 /**
- * This runtime exception is thrown when an attempt is made to create an array
- * whose size would be less than zero.
+ * Thrown when an attempt is made to create an array with a size of less than
+ * zero.
  */
 public class NegativeArraySizeException extends RuntimeException {
 
     private static final long serialVersionUID = -8960118058596991861L;
 
     /**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
-	public NegativeArraySizeException() {
-		super();
-	}
+     * Constructs a new {@code NegativeArraySizeException} that includes the
+     * current stack trace.
+     */
+    public NegativeArraySizeException() {
+        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 NegativeArraySizeException(String detailMessage) {
-		super(detailMessage);
-	}
+    /**
+     * Constructs a new {@code NegativeArraySizeException} with the current
+     * stack trace and the specified detail message.
+     * 
+     * @param detailMessage
+     *            the detail message for this exception.
+     */
+    public NegativeArraySizeException(String detailMessage) {
+        super(detailMessage);
+    }
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NoClassDefFoundError.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NoClassDefFoundError.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NoClassDefFoundError.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NoClassDefFoundError.java Sat May  2 08:09:50 2009
@@ -17,30 +17,30 @@
 
 package java.lang;
 
-
 /**
- * This error is thrown when the VM is unable to locate a class which it has
- * been asked to load.
+ * Thrown when the virtual machine is unable to locate a class which it has been
+ * asked to load.
  */
 public class NoClassDefFoundError extends LinkageError {
 
     private static final long serialVersionUID = 9095859863287012458L;
 
     /**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
-	public NoClassDefFoundError() {
-		super();
-	}
+     * Constructs a new {@code NoClassDefFoundError} that includes the current
+     * stack trace.
+     */
+    public NoClassDefFoundError() {
+        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 NoClassDefFoundError(String detailMessage) {
-		super(detailMessage);
-	}
+    /**
+     * Constructs a new {@code NoClassDefFoundError} with the current stack
+     * trace and the specified detail message.
+     * 
+     * @param detailMessage
+     *            the detail message for this error.
+     */
+    public NoClassDefFoundError(String detailMessage) {
+        super(detailMessage);
+    }
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NoSuchFieldError.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NoSuchFieldError.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NoSuchFieldError.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NoSuchFieldError.java Sat May  2 08:09:50 2009
@@ -17,32 +17,32 @@
 
 package java.lang;
 
-
 /**
- * This error is thrown when the VM notices that a an attempt is being made to
- * reference a field of a class which does not exist in that class.
+ * Thrown when the virtual machine notices that a program tries to reference,
+ * on a class or object, a field that does not exist.
  * <p>
- * Note that this can only occur when inconsistant class files are being loaded.
+ * Note that this can only occur when inconsistent class files are being loaded.
  */
 public class NoSuchFieldError extends IncompatibleClassChangeError {
 
     private static final long serialVersionUID = -3456430195886129035L;
 
     /**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
-	public NoSuchFieldError() {
-		super();
-	}
+     * Constructs a new {@code NoSuchFieldError} that includes the current stack
+     * trace.
+     */
+    public NoSuchFieldError() {
+        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 NoSuchFieldError(String detailMessage) {
-		super(detailMessage);
-	}
+    /**
+     * Constructs a new {@code NoSuchFieldError} with the current stack trace
+     * and the specified detail message.
+     * 
+     * @param detailMessage
+     *            the detail message for this error.
+     */
+    public NoSuchFieldError(String detailMessage) {
+        super(detailMessage);
+    }
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NoSuchFieldException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NoSuchFieldException.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NoSuchFieldException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NoSuchFieldException.java Sat May  2 08:09:50 2009
@@ -17,30 +17,30 @@
 
 package java.lang;
 
-
 /**
- * This exception is thrown when a program attempts to access a field which does
- * not exist in a class
+ * Thrown when the virtual machine notices that a program tries to reference,
+ * on a class or object, a field that does not exist.
  */
 public class NoSuchFieldException extends java.lang.Exception {
 
     private static final long serialVersionUID = -6143714805279938260L;
 
     /**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
-	public NoSuchFieldException() {
-		super();
-	}
+     * Constructs a new {@code NoSuchFieldException} that includes the current
+     * stack trace.
+     */
+    public NoSuchFieldException() {
+        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 NoSuchFieldException(String detailMessage) {
-		super(detailMessage);
-	}
+    /**
+     * Constructs a new {@code NoSuchFieldException} with the current stack
+     * trace and the specified detail message.
+     * 
+     * @param detailMessage
+     *            the detail message for this exception.
+     */
+    public NoSuchFieldException(String detailMessage) {
+        super(detailMessage);
+    }
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NoSuchMethodError.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NoSuchMethodError.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NoSuchMethodError.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NoSuchMethodError.java Sat May  2 08:09:50 2009
@@ -17,31 +17,31 @@
 
 package java.lang;
 
-
 /**
- * This error is thrown when the VM notices that a an attempt is being made to
- * reference a method of a class which does not exist in that class.
+ * Thrown when the virtual machine notices that a program tries to reference,
+ * on a class or object, a method that does not exist.
  */
 public class NoSuchMethodError extends IncompatibleClassChangeError {
 
     private static final long serialVersionUID = -3765521442372831335L;
 
     /**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
-	public NoSuchMethodError() {
-		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 NoSuchMethodError(String detailMessage) {
-		super(detailMessage);
-	}
+     * Constructs a new {@code NoSuchMethodError} that includes the current
+     * stack trace.
+     */
+    public NoSuchMethodError() {
+        super();
+    }
+
+    /**
+     * Constructs a new {@code NoSuchMethodError} with the current stack trace
+     * and the specified detail message.
+     * 
+     * @param detailMessage
+     *            the detail message for this exception.
+     */
+    public NoSuchMethodError(String detailMessage) {
+        super(detailMessage);
+    }
 
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NoSuchMethodException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NoSuchMethodException.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NoSuchMethodException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NoSuchMethodException.java Sat May  2 08:09:50 2009
@@ -17,31 +17,31 @@
 
 package java.lang;
 
-
 /**
- * This exception is thrown when a program attempts to access a method which
- * does not exist in a class.
+ * Thrown when the virtual machine notices that a program tries to reference,
+ * on a class or object, a method that does not exist.
  */
 public class NoSuchMethodException extends java.lang.Exception {
 
     private static final long serialVersionUID = 5034388446362600923L;
 
     /**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
-	public NoSuchMethodException() {
-		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 NoSuchMethodException(String detailMessage) {
-		super(detailMessage);
-	}
+     * Constructs a new {@code NoSuchMethodException} that includes the current
+     * stack trace.
+     */
+   public NoSuchMethodException() {
+        super();
+    }
+
+   /**
+     * Constructs a new {@code NoSuchMethodException} with the current stack
+     * trace and the specified detail message.
+     * 
+     * @param detailMessage
+     *            the detail message for this exception.
+     */
+    public NoSuchMethodException(String detailMessage) {
+        super(detailMessage);
+    }
 
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NullPointerException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NullPointerException.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NullPointerException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NullPointerException.java Sat May  2 08:09:50 2009
@@ -17,32 +17,34 @@
 
 package java.lang;
 
-
 /**
- * This runtime exception is thrown when an attempt is made to access a field or
- * method of an instance or an element of an array when there is no instance or
- * array to use (i.e. the pointer is null).
+ * Thrown when a program tries to access a field or method of an object or an
+ * element of an array when there is no instance or array to use, that is if the
+ * object or array points to {@code null}. It also occurs in some other, less
+ * obvious circumstances, like a {@code throw e} statement where the {@link
+ * Throwable} reference is {@code null}.
  */
 public class NullPointerException extends RuntimeException {
 
     private static final long serialVersionUID = 5162710183389028792L;
 
     /**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
-	public NullPointerException() {
-		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 NullPointerException(String detailMessage) {
-		super(detailMessage);
-	}
+     * Constructs a new {@code NullPointerException} that includes the current
+     * stack trace.
+     */
+    public NullPointerException() {
+        super();
+    }
+
+    /**
+     * Constructs a new {@code NullPointerException} with the current stack
+     * trace and the specified detail message.
+     * 
+     * @param detailMessage
+     *            the detail message for this exception.
+     */
+    public NullPointerException(String detailMessage) {
+        super(detailMessage);
+    }
 
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Number.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Number.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Number.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Number.java Sat May  2 08:09:50 2009
@@ -19,62 +19,67 @@
 
 
 /**
- * Number is the abstract superclass of the classes which represent numeric base
- * types (i.e. all but Character, Boolean, and Void).
+ * The abstract superclass of the classes which represent numeric base types
+ * (that is {@link Byte}, {@link Short}, {@link Integer}, {@link Long},
+ * {@link Float}, and {@link Double}. 
  */
 public abstract class Number implements java.io.Serializable {
 
-	private static final long serialVersionUID = -8742448824652078965L;
+    private static final long serialVersionUID = -8742448824652078965L;
 
-	/**
-	 * Number constructor. Included for spec compatability.
-	 */
-	public Number() {
-	}
-
-	/**
-	 * Answers the byte value which the receiver represents
-	 * 
-	 * @return byte the value of the receiver.
-	 */
-	public byte byteValue() {
-		return (byte) intValue();
-	}
-
-	/**
-	 * Answers the double value which the receiver represents
-	 * 
-	 * @return double the value of the receiver.
-	 */
-	public abstract double doubleValue();
-
-	/**
-	 * Answers the float value which the receiver represents
-	 * 
-	 * @return float the value of the receiver.
-	 */
-	public abstract float floatValue();
-
-	/**
-	 * Answers the int value which the receiver represents
-	 * 
-	 * @return int the value of the receiver.
-	 */
-	public abstract int intValue();
-
-	/**
-	 * Answers the long value which the receiver represents
-	 * 
-	 * @return long the value of the receiver.
-	 */
-	public abstract long longValue();
-
-	/**
-	 * Answers the short value which the receiver represents
-	 * 
-	 * @return short the value of the receiver.
-	 */
-	public short shortValue() {
-		return (short) intValue();
-	}
+    /**
+     * Empty default constructor.
+     */
+    public Number() {
+    }
+
+    /**
+     * Returns this object's value as a byte. Might involve rounding and/or
+     * truncating the value, so it fits into a byte.  
+     * 
+     * @return the primitive byte value of this object.
+     */
+    public byte byteValue() {
+        return (byte) intValue();
+    }
+
+    /**
+     * Returns this object's value as a double. Might involve rounding.
+     * 
+     * @return the primitive double value of this object.
+     */
+    public abstract double doubleValue();
+
+    /**
+     * Returns this object's value as a float. Might involve rounding.
+     * 
+     * @return the primitive float value of this object.
+     */
+    public abstract float floatValue();
+
+    /**
+     * Returns this object's value as an int. Might involve rounding and/or
+     * truncating the value, so it fits into an int.
+     * 
+     * @return the primitive int value of this object.
+     */
+    public abstract int intValue();
+
+    /**
+     * Returns this object's value as a long. Might involve rounding and/or
+     * truncating the value, so it fits into a long.
+     * 
+     * @return the primitive long value of this object.
+     */
+    public abstract long longValue();
+
+    /**
+     * Returns this object's value as a short. Might involve rounding and/or
+     * truncating the value, so it fits into a short.
+     * 
+     * @return the primitive short value of this object.
+     */
+    public short shortValue() {
+        return (short) intValue();
+    }
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NumberFormatException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NumberFormatException.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NumberFormatException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/NumberFormatException.java Sat May  2 08:09:50 2009
@@ -18,26 +18,27 @@
 package java.lang;
 
 /**
- * This runtime exception is thrown when a "string to number" conversion routine
- * is passed an invalid value.
+ * Thrown when an invalid value is passed to a string-to-number conversion
+ * method.
  */
-public class NumberFormatException extends IllegalArgumentException {
+public class NumberFormatException extends java.lang.IllegalArgumentException {
 
     private static final long serialVersionUID = -2848938806368998894L;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
+     * Constructs a new {@code NumberFormatException} that includes the current
+     * stack trace.
      */
     public NumberFormatException() {
         super();
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
+     * Constructs a new {@code NumberFormatException} with the current stack
+     * trace and the specified detail message.
      * 
      * @param detailMessage
-     *            String The detail message for the exception.
+     *            the detail message for this exception.
      */
     public NumberFormatException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/OutOfMemoryError.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/OutOfMemoryError.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/OutOfMemoryError.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/OutOfMemoryError.java Sat May  2 08:09:50 2009
@@ -17,32 +17,31 @@
 
 package java.lang;
 
-
 /**
- * This error is thrown when a request is made for more memory either as a
- * result of the running program, or because of the internal behavior of the
- * virtual machine which can not be satisfied using the available platform
- * resources.
+ * Thrown when a request for memory is made that can not be satisfied using the
+ * available platform resources. Such a request may be made by both the running
+ * application or by an internal function of the virtual machine.
  */
-public class OutOfMemoryError extends VirtualMachineError {
+public class OutOfMemoryError extends java.lang.VirtualMachineError {
 
     private static final long serialVersionUID = 8228564086184010517L;
 
     /**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
-	public OutOfMemoryError() {
-		super();
-	}
+     * Constructs a new {@code OutOfMemoryError} that includes the current stack
+     * trace.
+     */
+    public OutOfMemoryError() {
+        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 OutOfMemoryError(String detailMessage) {
-		super(detailMessage);
-	}
+    /**
+     * Constructs a new {@code OutOfMemoryError} with the current stack trace
+     * and the specified detail message.
+     * 
+     * @param detailMessage
+     *            the detail message for this error.
+     */
+    public OutOfMemoryError(String detailMessage) {
+        super(detailMessage);
+    }
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Override.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Override.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Override.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Override.java Sat May  2 08:09:50 2009
@@ -22,10 +22,10 @@
 import java.lang.annotation.Target;
 
 /**
- * An annotation to indicate that a method is intended to override a superclass
- * method. This provides a compile-time assertion that a method actually
- * overrides the superclass method.
- * 
+ * Annotation type used to mark methods that override a method declaration in a
+ * superclass. Compilers produce an error if a method annotated with @Override
+ * does not actually override a method in a superclass.
+ *
  * @since 1.5
  */
 @Target(ElementType.METHOD)

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Process.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Process.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Process.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Process.java Sat May  2 08:09:50 2009
@@ -21,65 +21,63 @@
 import java.io.OutputStream;
 
 /**
- * Instances of class Process provide control of and access to platform
- * processes.
+ * Represents an external process. Enables writing to, reading from, destroying,
+ * and waiting for the external process, as well as querying its exit value.
+ *
+ * @see Runtime#exec
+ * @see ProcessBuilder#start()
  */
 public abstract class Process {
 
     /**
-     * Terminates the receiver and closes any associated streams.
+     * Terminates this process and closes any associated streams.
      */
     abstract public void destroy();
 
     /**
-     * Answers the exit value of the receiving Process. It is available only
-     * when the OS subprocess is finished.
-     * 
-     * @return The exit value of the receiver.
+     * Returns the exit value of the native process represented by this object.
+     * It is available only when the native process has terminated.
      * 
+     * @return the exit value of this process.
      * @throws IllegalThreadStateException
-     *             If the receiver has not terminated.
+     *             if this process has not terminated.
      */
     abstract public int exitValue();
 
     /**
-     * Answers the receiver's error output stream.
-     * <p>
-     * Note: This is an InputStream which allows reading of the other threads
-     * "stderr".
+     * Returns an input stream that is connected to the error stream
+     * <em>(stderr)</em> of the native process represented by this object.
      * 
-     * @return The error stream associated with the receiver
+     * @return the input stream to read from the error stream associated with
+     *         the native process.
      */
     abstract public InputStream getErrorStream();
 
     /**
-     * Answers the receiver's standard input stream
-     * <p>
-     * Note: This is an InputStream which allows reading from the other process'
-     * "stdout".
+     * Returns an input stream that is connected to the standard output stream
+     * <em>(stdout)</em> of the native process represented by this object.
      * 
-     * @return The receiver's process' stdin.
+     * @return the input stream to read from the output stream associated with
+     *         the native process.
      */
     abstract public InputStream getInputStream();
 
     /**
-     * Answers the receiver's standard output stream
-     * <p>
-     * Note: This is an OutputStream which allows writing to the other process'
-     * "stdin".
+     * Returns an output stream that is connected to the standard input stream
+     * <em>(stdin)</em> of the native process represented by this object.
      * 
-     * @return The receiver's process' stdout.
+     * @return the output stream to write to the input stream associated with
+     *         the native process.
      */
     abstract public OutputStream getOutputStream();
 
     /**
-     * Causes the calling thread to wait for the process associated with the
-     * receiver to finish executing.
-     * 
-     * @return The exit value of the Process being waited on
+     * Causes the calling thread to wait for the native process associated with
+     * this object to finish executing.
      * 
+     * @return the exit value of the native process being waited on.
      * @throws InterruptedException
-     *             If the calling thread is interrupted
+     *             if the calling thread is interrupted.
      */
     abstract public int waitFor() throws InterruptedException;
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/ProcessBuilder.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/ProcessBuilder.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/ProcessBuilder.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/ProcessBuilder.java Sat May  2 08:09:50 2009
@@ -23,10 +23,8 @@
 import java.util.Map;
 
 /**
- * <p>
- * A builder for creating OS-specific processes.
- * </p>
- * 
+ * Creates operating system processes.
+ *
  * @since 1.5
  */
 public final class ProcessBuilder {
@@ -40,26 +38,26 @@
     private boolean redirectErrorStream;
 
     /**
-     * <p>
-     * Constructs an instance with the given command.
-     * </p>
+     * Constructs a new {@code ProcessBuilder} instance with the specified
+     * operating system program and its arguments.
      * 
      * @param command
-     *            The program and arguments.
+     *            the requested operating system program and its arguments.
      */
     public ProcessBuilder(String... command) {
         this(toList(command));
     }
 
     /**
-     * <p>
-     * Constructs an instance with the given command.
-     * </p>
+     * Constructs a new {@code ProcessBuilder} instance with the specified
+     * operating system program and its arguments. Note that the list passed to
+     * this constructor is not copied, so any subsequent updates to it are
+     * reflected in this instance's state.
      * 
      * @param command
-     *            The program and arguments.
+     *            the requested operating system program and its arguments.
      * @throws NullPointerException
-     *             if <code>command</code> is <code>null</code>.
+     *             if {@code command} is {@code null}.
      */
     public ProcessBuilder(List<String> command) {
         super();
@@ -72,43 +70,37 @@
     }
 
     /**
-     * <p>
-     * The builder's current program and arguments. The returned value is
-     * considered live and modifications to it will change the state of the
-     * instance.
-     * </p>
-     * 
-     * @return The program and arguments currently set.
+     * Returns this process builder's current program and arguments. Note that
+     * the returned list is not a copy and modifications to it will change the
+     * state of this instance.
+     *
+     * @return this process builder's program and arguments.
      */
     public List<String> command() {
         return command;
     }
 
     /**
-     * <p>
-     * Changes the program and arguments to the command given.
-     * </p>
+     * Changes the program and arguments of this process builder.
      * 
      * @param command
-     *            The program and arguments.
-     * @return A reference to this instance.
+     *            the new operating system program and its arguments.
+     * @return this process builder instance.
      */
     public ProcessBuilder command(String... command) {
         return command(toList(command));
     }
 
     /**
-     * <p>
-     * Changes the program and arguments to the command given. The list passed
-     * is not copied, so any subsequent updates to it are reflected in this
-     * instance's state.
-     * </p>
-     * 
+     * Changes the program and arguments of this process builder. Note that the
+     * list passed to this method is not copied, so any subsequent updates to it
+     * are reflected in this instance's state.
+     *
      * @param command
-     *            The program and arguments.
-     * @return A reference to this instance.
+     *            the new operating system program and its arguments.
+     * @return this process builder instance.
      * @throws NullPointerException
-     *             if <code>command</code> is <code>null</code>.
+     *             if {@code command} is {@code null}.
      */
     public ProcessBuilder command(List<String> command) {
         if (command == null) {
@@ -119,28 +111,24 @@
     }
 
     /**
-     * <p>
-     * The working directory that's currently set. If this value is
-     * <code>null</code>, then the working directory of the Java process is
-     * used.
-     * </p>
+     * Returns the working directory of this process builder. If {@code null} is
+     * returned, then the working directory of the Java process is used when a
+     * process is started.
      * 
-     * @return The current working directory, which may be <code>null</code>.
+     * @return the current working directory, may be {@code null}.
      */
     public File directory() {
         return directory;
     }
 
     /**
-     * <p>
-     * Changes the working directory to the directory given. If the given
-     * directory is <code>null</code>, then the working directory of the Java
+     * Changes the working directory of this process builder. If the specified
+     * directory is {@code null}, then the working directory of the Java
      * process is used when a process is started.
-     * </p>
-     * 
+     *
      * @param directory
-     *            The working directory to set.
-     * @return A reference to this instance.
+     *            the new working directory for this process builder.
+     * @return this process builder instance.
      */
     public ProcessBuilder directory(File directory) {
         this.directory = directory;
@@ -148,42 +136,39 @@
     }
 
     /**
-     * <p>
-     * The builder's current environment. When an instance is created, the
-     * environment is populated with a copy of the environment, as returned by
-     * {@link System#getenv()}. The Map returned is live and any changes made
-     * to it are reflected in this instance's state.
-     * </p>
-     * 
-     * @return The Map of the current environment variables.
+     * Returns this process builder's current environment. When a process
+     * builder instance is created, the environment is populated with a copy of
+     * the environment, as returned by {@link System#getenv()}. Note that the
+     * map returned by this method is not a copy and any changes made to it are
+     * reflected in this instance's state.
+     *
+     * @return the map containing this process builder's environment variables.
      */
     public Map<String, String> environment() {
         return environment;
     }
 
     /**
-     * <p>
-     * Indicates whether or not the standard error should be redirected to
-     * standard output. If redirected, the {@link Process#getErrorStream()} will
-     * always return end of stream and standard error is written to
+     * Indicates whether the standard error should be redirected to standard
+     * output. If redirected, the {@link Process#getErrorStream()} will always
+     * return end of stream and standard error is written to
      * {@link Process#getInputStream()}.
-     * </p>
-     * 
-     * @return Indicates whether or not standard error is redirected.
+     *
+     * @return {@code true} if the standard error is redirected; {@code false}
+     *         otherwise.
      */
     public boolean redirectErrorStream() {
         return redirectErrorStream;
     }
 
     /**
-     * <p>
-     * Changes the state of whether or not standard error is redirected.
-     * </p>
+     * Changes the state of whether or not standard error is redirected to
+     * standard output.
      * 
      * @param redirectErrorStream
-     *            <code>true</code> to redirect standard error,
-     *            <code>false</code> if not.
-     * @return A reference to this instance.
+     *            {@code true} to redirect standard error, {@code false}
+     *            otherwise.
+     * @return this process builder instance.
      */
     public ProcessBuilder redirectErrorStream(boolean redirectErrorStream) {
         this.redirectErrorStream = redirectErrorStream;
@@ -191,14 +176,11 @@
     }
 
     /**
-     * <p>
-     * Starts a new process based on the current state of the builder.
-     * </p>
-     * 
-     * @return The new process that was started.
+     * Starts a new process based on the current state of this process builder.
+     *
+     * @return the new {@code Process} instance.
      * @throws NullPointerException
-     *             if any of the elements of {@link #command()} are
-     *             <code>null</code>.
+     *             if any of the elements of {@link #command()} is {@code null}.
      * @throws IndexOutOfBoundsException
      *             if {@link #command()} is empty.
      * @throws SecurityException

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Readable.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Readable.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Readable.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Readable.java Sat May  2 08:09:50 2009
@@ -20,23 +20,21 @@
 import java.nio.CharBuffer;
 
 /**
- * Readable marks that the implementing class provides character sequence.
- * Readable gives a reference to character sequence from within itself to caller
- * through a <code>CharBuffer</code> parameter of the <code>read</code>
- * method.
+ * Represents a sequence of characters that can be incrementally read (copied)
+ * into a {@link CharBuffer}.
  */
 public interface Readable {
 
-	/**
-	 * Reads the characters into the given <code>CharBuffer</code>. The
-	 * maximum number of characters read is <code>CharBuffer.remaining()</code>.
-	 * 
-	 * @param cb
-	 *            the buffer to be filled in by the characters read
-	 * @return the number of characters actually read, or -1 if this
-	 *         <code>Readable</code> reaches its end
-	 * @throws IOException
-	 *             if some I/O operations fail
-	 */
-	int read(CharBuffer cb) throws IOException;
+    /**
+     * Reads characters into the specified {@code CharBuffer}. The maximum
+     * number of characters read is {@code CharBuffer.remaining()}.
+     * 
+     * @param cb
+     *            the buffer to be filled with characters read.
+     * @return the number of characters actually read, or -1 if this
+     *         {@code Readable} reaches its end
+     * @throws IOException
+     *             if an I/O error occurs.
+     */
+    int read(CharBuffer cb) throws IOException;
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Runnable.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Runnable.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Runnable.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Runnable.java Sat May  2 08:09:50 2009
@@ -19,14 +19,15 @@
 
 
 /**
- * The runnable interface must be implemented by all classes which want to be
- * run as threads.
- * 
- * @see Thread
+ * Represents a command that can be executed. Often used to run code in a
+ * different {@link Thread}.
  */
 public interface Runnable {
-	/**
-	 * Begin doing the active part of the class' code.
-	 */
-	public void run();
+
+    /**
+     * Starts executing the active part of the class' code. This method is
+     * called when a thread is started that has been created with a class which
+     * implements {@code Runnable}.
+     */
+    public void run();
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/RuntimeException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/RuntimeException.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/RuntimeException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/RuntimeException.java Sat May  2 08:09:50 2009
@@ -17,54 +17,57 @@
 
 package java.lang;
 
-
 /**
- * This class is the superclass of all classes which represent exceptional
- * conditions which occur as a result of the running of the virtual machine.
+ * {@code RuntimeException} is the superclass of all classes that represent
+ * exceptional conditions which occur as a result of executing an application in
+ * the virtual machine. Unlike checked exceptions (exceptions where the type
+ * doesn't extend {@code RuntimeException} or {@link Error}), the compiler does
+ * not require code to handle runtime exceptions.
  */
 public class RuntimeException extends Exception {
-	
-	private static final long serialVersionUID = -7034897190745766939L;
+    
+    private static final long serialVersionUID = -7034897190745766939L;
 
-	/**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
-	public RuntimeException() {
-		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 RuntimeException(String detailMessage) {
-		super(detailMessage);
-	}
-
-	/**
-	 * Constructs a new instance of this class with its walkback, message and
-	 * cause filled in.
-	 * 
-	 * @param detailMessage
-	 *            String The detail message for the exception.
-	 * @param throwable
-	 *            The cause of this Throwable
-	 */
-	public RuntimeException(String detailMessage, Throwable throwable) {
-		super(detailMessage, throwable);
-	}
-
-	/**
-	 * Constructs a new instance of this class with its walkback and cause
-	 * filled in.
-	 * 
-	 * @param throwable
-	 *            The cause of this Throwable
-	 */
-	public RuntimeException(Throwable throwable) {
-		super(throwable);
-	}
+    /**
+     * Constructs a new {@code RuntimeException} that includes the current stack
+     * trace.
+     */
+    public RuntimeException() {
+        super();
+    }
+
+    /**
+     * Constructs a new {@code RuntimeException} with the current stack trace
+     * and the specified detail message.
+     * 
+     * @param detailMessage
+     *            the detail message for this exception.
+     */
+    public RuntimeException(String detailMessage) {
+        super(detailMessage);
+    }
+
+   /**
+     * Constructs a new {@code RuntimeException} with the current stack trace,
+     * the specified detail message and the specified cause.
+     * 
+     * @param detailMessage
+     *            the detail message for this exception.
+     * @param throwable
+     *            the cause of this exception.
+     */
+    public RuntimeException(String detailMessage, Throwable throwable) {
+        super(detailMessage, throwable);
+    }
+
+    /**
+     * Constructs a new {@code RuntimeException} with the current stack trace
+     * and the specified cause.
+     * 
+     * @param throwable
+     *            the cause of this exception.
+     */
+    public RuntimeException(Throwable throwable) {
+        super(throwable);
+    }
 }



Mime
View raw message