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 &ge; 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">