JDK 8 code review request for 7062430 "Minor iconsistency in ulp descriptions"

[Mike Duigou]

Perhaps a linkplain from the method javadoc to an anchor in the Math class javadoc could be added so that an explanation for the added definition is available.

Mike

On Jul 14 2011, at 18:14 , Joe Darcy wrote:

> Hello.
> 
> Please review this small doc change to spell out what "ulp" means in the methods named "ulp" in the Math and StrictMath classes; patch below, webrev at:
> 
>   7062430 "Minor iconsistency in ulp descriptions"
>   http://cr.openjdk.java.net/~darcy/7062430.0/
> 
> Due to paragraph reformatting, the change takes up many more physical lines than logical ones.  In each of the four ulp methods (for for float and one for double in each of Math and StrictMath) the phrase
> 
>   "An ulp of a [...] value is the positive distance..."
> 
> is replaced with
> 
>   "An ulp, unit in the last place, of a [...] value is the positive distance..."
> 
> Additionally, the reference to ulp in one the opening paragraphs of the Math class description is replaced with a link to one of the ulp methods in Math.
> 
> Thanks,
> 
> -Joe
> 
> --- old/src/share/classes/java/lang/Math.java    2011-07-14 18:07:17.000000000 -0700
> +++ new/src/share/classes/java/lang/Math.java    2011-07-14 18:07:17.000000000 -0700
> @@ -50,34 +50,34 @@
> *
> * <p>The quality of implementation specifications concern two
> * properties, accuracy of the returned result and monotonicity of the
> - * method.  Accuracy of the floating-point {@code Math} methods
> - * is measured in terms of <i>ulps</i>, units in the last place.  For
> - * a given floating-point format, an ulp of a specific real number
> - * value is the distance between the two floating-point values
> - * bracketing that numerical value.  When discussing the accuracy of a
> - * method as a whole rather than at a specific argument, the number of
> - * ulps cited is for the worst-case error at any argument.  If a
> - * method always has an error less than 0.5 ulps, the method always
> - * returns the floating-point number nearest the exact result; such a
> - * method is <i>correctly rounded</i>.  A correctly rounded method is
> - * generally the best a floating-point approximation can be; however,
> - * it is impractical for many floating-point methods to be correctly
> - * rounded.  Instead, for the {@code Math} class, a larger error
> - * bound of 1 or 2 ulps is allowed for certain methods.  Informally,
> - * with a 1 ulp error bound, when the exact result is a representable
> - * number, the exact result should be returned as the computed result;
> - * otherwise, either of the two floating-point values which bracket
> - * the exact result may be returned.  For exact results large in
> - * magnitude, one of the endpoints of the bracket may be infinite.
> - * Besides accuracy at individual arguments, maintaining proper
> - * relations between the method at different arguments is also
> - * important.  Therefore, most methods with more than 0.5 ulp errors
> - * are required to be <i>semi-monotonic</i>: whenever the mathematical
> - * function is non-decreasing, so is the floating-point approximation,
> - * likewise, whenever the mathematical function is non-increasing, so
> - * is the floating-point approximation.  Not all approximations that
> - * have 1 ulp accuracy will automatically meet the monotonicity
> - * requirements.
> + * method.  Accuracy of the floating-point {@code Math} methods is
> + * measured in terms of <i>ulps</i>, units in the last place.  For a
> + * given floating-point format, an {@linkplain #ulp(double) ulp} of a
> + * specific real number value is the distance between the two
> + * floating-point values bracketing that numerical value.  When
> + * discussing the accuracy of a method as a whole rather than at a
> + * specific argument, the number of ulps cited is for the worst-case
> + * error at any argument.  If a method always has an error less than
> + * 0.5 ulps, the method always returns the floating-point number
> + * nearest the exact result; such a method is <i>correctly
> + * rounded</i>.  A correctly rounded method is generally the best a
> + * floating-point approximation can be; however, it is impractical for
> + * many floating-point methods to be correctly rounded.  Instead, for
> + * the {@code Math} class, a larger error bound of 1 or 2 ulps is
> + * allowed for certain methods.  Informally, with a 1 ulp error bound,
> + * when the exact result is a representable number, the exact result
> + * should be returned as the computed result; otherwise, either of the
> + * two floating-point values which bracket the exact result may be
> + * returned.  For exact results large in magnitude, one of the
> + * endpoints of the bracket may be infinite.  Besides accuracy at
> + * individual arguments, maintaining proper relations between the
> + * method at different arguments is also important.  Therefore, most
> + * methods with more than 0.5 ulp errors are required to be
> + * <i>semi-monotonic</i>: whenever the mathematical function is
> + * non-decreasing, so is the floating-point approximation, likewise,
> + * whenever the mathematical function is non-increasing, so is the
> + * floating-point approximation.  Not all approximations that have 1
> + * ulp accuracy will automatically meet the monotonicity requirements.
> *
> * @author  unascribed
> * @author  Joseph D. Darcy
> @@ -940,11 +940,11 @@
>    }
>    /**
> -     * Returns the size of an ulp of the argument.  An ulp of a
> -     * {@code double} value is the positive distance between this
> -     * floating-point value and the {@code double} value next
> -     * larger in magnitude.  Note that for non-NaN <i>x</i>,
> -     * <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
> +     * Returns the size of an ulp of the argument.  An ulp, unit in
> +     * the last place, of a {@code double} value is the positive
> +     * distance between this floating-point value and the {@code
> +     * double} value next larger in magnitude.  Note that for non-NaN
> +     * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
>     *
>     * <p>Special Cases:
>     * <ul>
> @@ -967,11 +967,11 @@
>    }
>    /**
> -     * Returns the size of an ulp of the argument.  An ulp of a
> -     * {@code float} value is the positive distance between this
> -     * floating-point value and the {@code float} value next
> -     * larger in magnitude.  Note that for non-NaN <i>x</i>,
> -     * <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
> +     * Returns the size of an ulp of the argument.  An ulp, unit in
> +     * the last place, of a {@code float} value is the positive
> +     * distance between this floating-point value and the {@code
> +     * float} value next larger in magnitude.  Note that for non-NaN
> +     * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
>     *
>     * <p>Special Cases:
>     * <ul>
> --- old/src/share/classes/java/lang/StrictMath.java    2011-07-14 18:07:18.000000000 -0700
> +++ new/src/share/classes/java/lang/StrictMath.java    2011-07-14 18:07:18.000000000 -0700
> @@ -932,11 +932,11 @@
>    }
>    /**
> -     * Returns the size of an ulp of the argument.  An ulp of a
> -     * {@code double} value is the positive distance between this
> -     * floating-point value and the {@code double} value next
> -     * larger in magnitude.  Note that for non-NaN <i>x</i>,
> -     * <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
> +     * Returns the size of an ulp of the argument.  An ulp, unit in
> +     * the last place, of a {@code double} value is the positive
> +     * distance between this floating-point value and the {@code
> +     * double} value next larger in magnitude.  Note that for non-NaN
> +     * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
>     *
>     * <p>Special Cases:
>     * <ul>
> @@ -959,11 +959,11 @@
>    }
>    /**
> -     * Returns the size of an ulp of the argument.  An ulp of a
> -     * {@code float} value is the positive distance between this
> -     * floating-point value and the {@code float} value next
> -     * larger in magnitude.  Note that for non-NaN <i>x</i>,
> -     * <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
> +     * Returns the size of an ulp of the argument.  An ulp, unit in
> +     * the last place, of a {@code float} value is the positive
> +     * distance between this floating-point value and the {@code
> +     * float} value next larger in magnitude.  Note that for non-NaN
> +     * <i>x</i>, <code>ulp(-<i>x</i>) == ulp(<i>x</i>)</code>.
>     *
>     * <p>Special Cases:
>     * <ul>
>