JDK 15 RFR of JDK-8240624: Note mapping of RoundingMode constants to equivalent IEEE 754-2019 policy

[Joe Darcy]

Hello,

Where such a mapping exists, it would be helpful to tie the policies 
represented by various RoundingMode constants to the equivalent rounding 
attribute defined by IEEE 754-2019, the latest version of the 
floating-point standard:

     JDK-8240624: Note mapping of RoundingMode constants to equivalent 
IEEE 754-2019 policy
     http://cr.openjdk.java.net/~darcy/8240624.0/

Please review the patch below; I'll update the file copyright year 
before pushing.

Thanks,

-Joe

--- old/src/java.base/share/classes/java/math/RoundingMode.java	2020-03-05 13:44:23.971037000 -0800
+++ new/src/java.base/share/classes/java/math/RoundingMode.java	2020-03-05 13:44:23.647037000 -0800
@@ -87,6 +87,12 @@
   * ({@link BigDecimal#ROUND_UP}, {@link BigDecimal#ROUND_DOWN},
   * etc. ).
   *
+ * @apiNote
+ * Five of the rounding modes defined in this class correspond to
+ * rounding direction attributes defined in IEEE 754-2019. Where
+ * present, this correspondence will be noted in the documentation of
+ * the particular constant.
+ *
   * @see     BigDecimal
   * @see     MathContext
   * @author  Josh Bloch
@@ -130,7 +136,9 @@
           * Rounding mode to round towards zero.  Never increments the digit
           * prior to a discarded fraction (i.e., truncates).  Note that this
           * rounding mode never increases the magnitude of the calculated value.
-         *
+         * This mode corresponds to the IEEE 754-2019 rounding
+         * attribute roundTowardZero.
+         *
           *<p>Example:
           *<table class="striped">
           * <caption>Rounding mode DOWN Examples</caption>
@@ -159,6 +167,8 @@
           * result is positive, behaves as for {@code RoundingMode.UP};
           * if negative, behaves as for {@code RoundingMode.DOWN}.  Note
           * that this rounding mode never decreases the calculated value.
+         * This mode corresponds to the IEEE 754-2019 rounding
+         * attribute roundTowardPositive.
           *
           *<p>Example:
           *<table class="striped">
@@ -188,6 +198,8 @@
           * result is positive, behave as for {@code RoundingMode.DOWN};
           * if negative, behave as for {@code RoundingMode.UP}.  Note that
           * this rounding mode never increases the calculated value.
+         * This mode corresponds to the IEEE 754-2019 rounding
+         * attribute roundTowardNegative.
           *
           *<p>Example:
           *<table class="striped">
@@ -219,6 +231,8 @@
           * fraction is ≥ 0.5; otherwise, behaves as for
           * {@code RoundingMode.DOWN}.  Note that this is the rounding
           * mode commonly taught at school.
+         * This mode corresponds to the IEEE 754-2019 rounding
+         * attribute roundTiesToAway.
           *
           *<p>Example:
           *<table class="striped">
@@ -286,6 +300,8 @@
           * chiefly used in the USA.  This rounding mode is analogous to
           * the rounding policy used for {@code float} and {@code double}
           * arithmetic in Java.
+         * This mode corresponds to the IEEE 754-2019 rounding
+         * attribute roundTiesToEven.
           *
           *<p>Example:
           *<table class="striped">