You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by te...@apache.org on 2009/05/02 10:09:57 UTC
svn commit: r770909 [5/10] - in
/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang: ./
ref/ reflect/
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);
+ }
}