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. + *

+ * Special cases: + *

+ *
• {@code abs(-0.0) = +0.0}
• + *
• {@code abs(+infinity) = +infinity}
• + *
• {@code abs(-infinity) = +infinity}
• + *
• {@code abs(NaN) = NaN}
• + *
+ * + * @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. + *

+ * Special cases: + *

+ *
• {@code abs(-0.0) = +0.0}
• + *
• {@code abs(+infinity) = +infinity}
• + *
• {@code abs(-infinity) = +infinity}
• + *
• {@code abs(NaN) = NaN}
• + *
+ * + * @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. + *

+ * 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. + *

+ * Special cases: + *

+ *
• {@code acos((anything > 1) = NaN}
• + *
• {@code acos((anything < -1) = NaN}
• + *
• {@code acos(NaN) = NaN}
• + *
+ * + * @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. + *

+ * Special cases: + *

+ *
• {@code asin((anything > 1)) = NaN}
• + *
• {@code asin((anything < -1)) = NaN}
• + *
• {@code asin(NaN) = NaN}
• + *
+ * + * @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. + *

+ * Special cases: + *

+ *
• {@code atan(+0.0) = +0.0}
• + *
• {@code atan(-0.0) = -0.0}
• + *
• {@code atan(+infinity) = +pi/2}
• + *
• {@code atan(-infinity) = -pi/2}
• + *
• {@code atan(NaN) = NaN}
• + *
+ * + * @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. + *

+ * Special cases: + *

+ *
• {@code atan2((anything), NaN ) = NaN;}
• + *
• {@code atan2(NaN , (anything) ) = NaN;}
• + *
• {@code atan2(+0.0, +(anything but NaN)) = +0.0}
• + *
• {@code atan2(-0.0, +(anything but NaN)) = -0.0}
• + *
• {@code atan2(+0.0, -(anything but NaN)) = +pi}
• + *
• {@code atan2(-0.0, -(anything but NaN)) = -pi}
• + *
• {@code atan2(+(anything but 0 and NaN), 0) = +pi/2}
• + *
• {@code atan2(-(anything but 0 and NaN), 0) = -pi/2}
• + *
• {@code atan2(+(anything but infinity and NaN), +infinity)} {@code =} + * {@code +0.0}
• + *
• {@code atan2(-(anything but infinity and NaN), +infinity)} {@code =} + * {@code -0.0}
• + *
• {@code atan2(+(anything but infinity and NaN), -infinity) = +pi}
• + *
• {@code atan2(-(anything but infinity and NaN), -infinity) = -pi}
• + *
• {@code atan2(+infinity, +infinity ) = +pi/4}
• + *
• {@code atan2(-infinity, +infinity ) = -pi/4}
• + *
• {@code atan2(+infinity, -infinity ) = +3pi/4}
• + *
• {@code atan2(-infinity, -infinity ) = -3pi/4}
• + *
• {@code atan2(+infinity, (anything but,0, NaN, and infinity))} + * {@code =} {@code +pi/2}
• + *
• {@code atan2(-infinity, (anything but,0, NaN, and infinity))} + * {@code =} {@code -pi/2}
• + *
+ * + * @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. + *

+ * Special cases: + *

+ *
• {@code cbrt(+0.0) = +0.0}
• + *
• {@code cbrt(-0.0) = -0.0}
• + *
• {@code cbrt(+infinity) = +infinity}
• + *
• {@code cbrt(-infinity) = -infinity}
• + *
• {@code cbrt(NaN) = NaN}
• + *
+ * * @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. + *

+ * Special cases: + *

+ *
• {@code ceil(+0.0) = +0.0}
• + *
• {@code ceil(-0.0) = -0.0}
• + *
• {@code ceil((anything in range (-1,0)) = -0.0}
• + *
• {@code ceil(+infinity) = +infinity}
• + *
• {@code ceil(-infinity) = -infinity}
• + *
• {@code ceil(NaN) = NaN}
• + *
+ * + * @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. + *

+ * Special cases: + *

+ *
• {@code cos(+infinity) = NaN}
• + *
• {@code cos(-infinity) = NaN}
• + *
• {@code cos(NaN) = NaN}
• + *
+ * + * @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. + *

+ * Special cases: + *

+ *
• {@code cosh(+infinity) = +infinity}
• + *
• {@code cosh(-infinity) = +infinity}
• + *
• {@code cosh(NaN) = NaN}
• + *
+ * * @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. + *

+ * Special cases: + *

+ *
• {@code exp(+infinity) = +infinity}
• + *
• {@code exp(-infinity) = +0.0}
• + *
• {@code exp(NaN) = NaN}
• + *
+ * + * @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 ed - 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 {@code e} + * {@code d}{@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. + *

+ * 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. + *

+ * Special cases: + *

+ *
• {@code expm1(+0.0) = +0.0}
• + *
• {@code expm1(-0.0) = -0.0}
• + *
• {@code expm1(+infinity) = +infinity}
• + *
• {@code expm1(-infinity) = -1.0}
• + *
• {@code expm1(NaN) = NaN}
• + *
+ * * @param d - * the value to compute the ed - 1 of - * @return the ed - 1 value of the argument. + * the value to compute the {@code e}{@code d} + * {@code - 1} of. + * @return the {@code e}{@code d}{@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. + *

+ * Special cases: + *

+ *
• {@code floor(+0.0) = +0.0}
• + *
• {@code floor(-0.0) = -0.0}
• + *
• {@code floor(+infinity) = +infinity}
• + *
• {@code floor(-infinity) = -infinity}
• + *
• {@code floor(NaN) = NaN}
• + *
+ * + * @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(x2+y2). 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(}{@code x}{@code 2}{@code +} + * {@code y}{@code 2}{@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. + *

+ * Special cases: + *

+ *
• {@code hypot(+infinity, (anything including NaN)) = +infinity}
• + *
• {@code hypot(-infinity, (anything including NaN)) = +infinity}
• + *
• {@code hypot((anything including NaN), +infinity) = +infinity}
• + *
• {@code hypot((anything including NaN), -infinity) = +infinity}
• + *
• {@code hypot(NaN, NaN) = NaN}
• + *
+ * * @param x - * a double number + * a double number. * @param y - * a double number - * @return the sqrt(x2+y2) value - * of the arguments. + * a double number. + * @return the {@code sqrt(}{@code x}{@code 2}{@code +} + * {@code y}{@code 2}{@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. + *

+ * Special cases: + *

+ *
• {@code IEEEremainder((anything), 0) = NaN}
• + *
• {@code IEEEremainder(+infinity, (anything)) = NaN}
• + *
• {@code IEEEremainder(-infinity, (anything)) = NaN}
• + *
• {@code IEEEremainder(NaN, (anything)) = NaN}
• + *
• {@code IEEEremainder((anything), NaN) = NaN}
• + *
• {@code IEEEremainder(x, +infinity) = x } where x is anything but + * +/-infinity
• + *
• {@code IEEEremainder(x, -infinity) = x } where x is anything but + * +/-infinity
• + *
+ * + * @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. + *

+ * Special cases: + *

+ *
• {@code log(+0.0) = -infinity}
• + *
• {@code log(-0.0) = -infinity}
• + *
• {@code log((anything < 0) = NaN}
• + *
• {@code log(+infinity) = +infinity}
• + *
• {@code log(-infinity) = NaN}
• + *
• {@code log(NaN) = NaN}
• + *
+ * + * @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. + *

+ * Special cases: + *

+ *
• {@code log10(+0.0) = -infinity}
• + *
• {@code log10(-0.0) = -infinity}
• + *
• {@code log10((anything < 0) = NaN}
• + *
• {@code log10(+infinity) = +infinity}
• + *
• {@code log10(-infinity) = NaN}
• + *
• {@code log10(NaN) = NaN}
• + *
+ * * @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. + *

+ * Special cases: + *

+ *
• {@code log1p(+0.0) = +0.0}
• + *
• {@code log1p(-0.0) = -0.0}
• + *
• {@code log1p((anything < 1)) = NaN}
• + *
• {@code log1p(-1.0) = -infinity}
• + *
• {@code log1p(+infinity) = +infinity}
• + *
• {@code log1p(-infinity) = NaN}
• + *
• {@code log1p(NaN) = NaN}
• + *
+ * * @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. + *

+ * Special cases: + *

+ *
• {@code max(NaN, (anything)) = NaN}
• + *
• {@code max((anything), NaN) = NaN}
• + *
• {@code max(+0.0, -0.0) = +0.0}
• + *
• {@code max(-0.0, +0.0) = +0.0}
• + *
+ * + * @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. + *

+ * Special cases: + *

+ *
• {@code max(NaN, (anything)) = NaN}
• + *
• {@code max((anything), NaN) = NaN}
• + *
• {@code max(+0.0, -0.0) = +0.0}
• + *
• {@code max(-0.0, +0.0) = +0.0}
• + *
+ * + * @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. + *

+ * Special cases: + *

+ *
• {@code min(NaN, (anything)) = NaN}
• + *
• {@code min((anything), NaN) = NaN}
• + *
• {@code min(+0.0, -0.0) = -0.0}
• + *
• {@code min(-0.0, +0.0) = -0.0}
• + *
+ * + * @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. + *

+ * Special cases: + *

+ *
• {@code min(NaN, (anything)) = NaN}
• + *
• {@code min((anything), NaN) = NaN}
• + *
• {@code min(+0.0, -0.0) = -0.0}
• + *
• {@code min(-0.0, +0.0) = -0.0}
• + *
+ * + * @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}. + *

+ * Special cases: + *

+ *
• {@code pow((anything), +0.0) = 1.0}
• + *
• {@code pow((anything), -0.0) = 1.0}
• + *
• {@code pow(x, 1.0) = x}
• + *
• {@code pow((anything), NaN) = NaN}
• + *
• {@code pow(NaN, (anything except 0)) = NaN}
• + *
• {@code pow(+/-(|x| > 1), +infinity) = +infinity}
• + *
• {@code pow(+/-(|x| > 1), -infinity) = +0.0}
• + *
• {@code pow(+/-(|x| < 1), +infinity) = +0.0}
• + *
• {@code pow(+/-(|x| < 1), -infinity) = +infinity}
• + *
• {@code pow(+/-1.0 , +infinity) = NaN}
• + *
• {@code pow(+/-1.0 , -infinity) = NaN}
• + *
• {@code pow(+0.0, (+anything except 0, NaN)) = +0.0}
• + *
• {@code pow(-0.0, (+anything except 0, NaN, odd integer)) = +0.0}
• + *
• {@code pow(+0.0, (-anything except 0, NaN)) = +infinity}
• + *
• {@code pow(-0.0, (-anything except 0, NAN, odd integer))} {@code =} + * {@code +infinity}
• + *
• {@code pow(-0.0, (odd integer)) = -pow( +0 , (odd integer) )}
• + *
• {@code pow(+infinity, (+anything except 0, NaN)) = +infinity}
• + *
• {@code pow(+infinity, (-anything except 0, NaN)) = +0.0}
• + *
• {@code pow(-infinity, (anything)) = -pow(0, (-anything))}
• + *
• {@code pow((-anything), (integer))} {@code =} + * {@code pow(-1,(integer))*pow(+anything,integer) }
• + *
• {@code pow((-anything except 0 and inf), (non-integer)) = NAN}
• + *
+ * + * @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. + *

+ * Special cases: + *

+ *
• {@code rint(+0.0) = +0.0}
• + *
• {@code rint(-0.0) = -0.0}
• + *
• {@code rint(+infinity) = +infinity}
• + *
• {@code rint(-infinity) = -infinity}
• + *
• {@code rint(NaN) = NaN}
• + *
+ * + * @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)}. + *

+ * Special cases: + *

+ *
• {@code round(+0.0) = +0.0}
• + *
• {@code round(-0.0) = +0.0}
• + *
• {@code round((anything > Long.MAX_VALUE) = Long.MAX_VALUE}
• + *
• {@code round((anything < Long.MIN_VALUE) = Long.MIN_VALUE}
• + *
• {@code round(+infintiy) = Long.MAX_VALUE}
• + *
• {@code round(-infintiy) = Long.MIN_VALUE}
• + *
• {@code round(NaN) = +0.0}
• + *
+ * + * @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)}. + *

+ * Special cases: + *

+ *
• {@code round(+0.0) = +0.0}
• + *
• {@code round(-0.0) = +0.0}
• + *
• {@code round((anything > Integer.MAX_VALUE) = Integer.MAX_VALUE}
• + *
• {@code round((anything < Integer.MIN_VALUE) = Integer.MIN_VALUE}
• + *
• {@code round(+infintiy) = Integer.MAX_VALUE}
• + *
• {@code round(-infintiy) = Integer.MIN_VALUE}
• + *
• {@code round(NaN) = +0.0}
• + *
+ * + * @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. + *

+ * Special cases: + *

+ *
• {@code signum(+0.0) = +0.0}
• + *
• {@code signum(-0.0) = -0.0}
• + *
• {@code signum(+infinity) = +1.0}
• + *
• {@code signum(-infinity) = -1.0}
• + *
• {@code signum(NaN) = NaN}
• + *
+ * * @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. + *

+ * Special cases: + *

+ *
• {@code signum(+0.0) = +0.0}
• + *
• {@code signum(-0.0) = -0.0}
• + *
• {@code signum(+infinity) = +1.0}
• + *
• {@code signum(-infinity) = -1.0}
• + *
• {@code signum(NaN) = NaN}
• + *
+ * * @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. + *

+ * Special cases: + *

+ *
• {@code sin(+0.0) = +0.0}
• + *
• {@code sin(-0.0) = -0.0}
• + *
• {@code sin(+infinity) = NaN}
• + *
• {@code sin(-infinity) = NaN}
• + *
• {@code sin(NaN) = NaN}
• + *
+ * + * @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. + *

+ * Special cases: + *

+ *
• {@code sinh(+0.0) = +0.0}
• + *
• {@code sinh(-0.0) = -0.0}
• + *
• {@code sinh(+infinity) = +infinity}
• + *
• {@code sinh(-infinity) = -infinity}
• + *
• {@code sinh(NaN) = NaN}
• + *
+ * * @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. + *

+ * Special cases: + *

+ *
• {@code sqrt(+0.0) = +0.0}
• + *
• {@code sqrt(-0.0) = -0.0}
• + *
• {@code sqrt( (anything < 0) ) = NaN}
• + *
• {@code sqrt(+infinity) = +infinity}
• + *
• {@code sqrt(NaN) = NaN}
• + *
+ * + * @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. + *

+ * Special cases: + *

+ *
• {@code tan(+0.0) = +0.0}
• + *
• {@code tan(-0.0) = -0.0}
• + *
• {@code tan(+infinity) = NaN}
• + *
• {@code tan(-infinity) = NaN}
• + *
• {@code tan(NaN) = NaN}
• + *
+ * + * @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. + *

+ * Special cases: + *

+ *
• {@code tanh(+0.0) = +0.0}
• + *
• {@code tanh(-0.0) = -0.0}
• + *
• {@code tanh(+infinity) = +1.0}
• + *
• {@code tanh(-infinity) = -1.0}
• + *
• {@code tanh(NaN) = NaN}
• + *
+ * * @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}. + *

+ * Special cases: + *

+ *
• + *
• + *
• + *
• + *
• + *
+ * + * @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}. + *

+ * Special cases: + *

+ *
• {@code toDegrees(+0.0) = +0.0}
• + *
• {@code toDegrees(-0.0) = -0.0}
• + *
• {@code toDegrees(+infinity) = +infinity}
• + *
• {@code toDegrees(-infinity) = -infinity}
• + *
• {@code toDegrees(NaN) = NaN}
• + *
+ * + * @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)}. + *

+ * Special cases: + *

+ *
• {@code ulp(+0.0) = Double.MIN_VALUE}
• + *
• {@code ulp(-0.0) = Double.MIN_VALUE}
• + *
• {@code ulp(+infintiy) = infinity}
• + *
• {@code ulp(-infintiy) = infinity}
• + *
• {@code ulp(NaN) = NaN}
• + *
+ * * @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)}. + *

+ * Special cases: + *

+ *
• {@code ulp(+0.0) = Float.MIN_VALUE}
• + *
• {@code ulp(-0.0) = Float.MIN_VALUE}
• + *
• {@code ulp(+infintiy) = infinity}
• + *
• {@code ulp(-infintiy) = infinity}
• + *
• {@code ulp(NaN) = NaN}
• + *
+ * * @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. *

- * Note: This is an InputStream which allows reading of the other threads - * "stderr". + * Returns an input stream that is connected to the error stream + * (stderr) 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 - *

- * 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 + * (stdout) 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 - *

- * 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 + * (stdin) 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; /** - *

- * A builder for creating OS-specific processes. - *

- * + * Creates operating system processes. + * * @since 1.5 */ public final class ProcessBuilder { @@ -40,26 +38,26 @@ private boolean redirectErrorStream; /** - *

- * Constructs an instance with the given command. - *

+ * 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)); } /** - *

- * Constructs an instance with the given command. - *

+ * 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 `command` is `null`. + * if {@code command} is {@code null}. */ public ProcessBuilder(List command) { super(); @@ -72,43 +70,37 @@ } /** - *

- * The builder's current program and arguments. The returned value is - * considered live and modifications to it will change the state of the - * instance. - *

- * - * @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 command() { return command; } /** - *

- * Changes the program and arguments to the command given. - *

+ * 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)); } /** - *

- * 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. - *

- * + * 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 `command` is `null`. + * if {@code command} is {@code null}. */ public ProcessBuilder command(List command) { if (command == null) { @@ -119,28 +111,24 @@ } /** - *

- * The working directory that's currently set. If this value is - * `null`, then the working directory of the Java process is - * used. - *

+ * 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 `null`. + * @return the current working directory, may be {@code null}. */ public File directory() { return directory; } /** - *

- * Changes the working directory to the directory given. If the given - * directory is `null`, 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. - *

- * + * * @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 @@ } /** - *

- * 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. - *

- * - * @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 environment() { return environment; } /** - *

- * 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()}. - *

- * - * @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; } /** - *

- * Changes the state of whether or not standard error is redirected. - *

+ * Changes the state of whether or not standard error is redirected to + * standard output. * * @param redirectErrorStream - * `true` to redirect standard error, - * `false` 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 @@ } /** - *

- * Starts a new process based on the current state of the builder. - *

- * - * @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 - * `null`. + * 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 `CharBuffer` parameter of the `read` - * 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 `CharBuffer`. The - * maximum number of characters read is `CharBuffer.remaining()`. - * - * @param cb - * the buffer to be filled in by the characters read - * @return the number of characters actually read, or -1 if this - * `Readable` 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); + } }