RFR: 8261366: Add discussion of IEEE 754 to BigDecimal

[Florent Guillaume]

On Mon, 8 Mar 2021 07:23:25 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> Informative update to BigDecimal and related classes to latest IEEE 754 terminology, including a discussion of the similarities and differences of BigDecimal and IEEE 754 decimal arithmetic.
> 
> Once the wording is finalized, I'll reflow any modified paragraphs and update the copyright years, etc.

src/java.base/share/classes/java/math/BigDecimal.java line 250:

> 248:  * values of a given format and produce a result in the same format.
> 249:  * A {@code BigDecimal}'s {@linkplain scale() scale} is equivalent to
> 250:  * negating an IEEE 754 value's exponent. {@code BigDecimal} values to

_to_ -> _do_

src/java.base/share/classes/java/math/BigDecimal.java line 260:

> 258:  * in {@code BigDecimal}, if a nonzero three-digit number and a
> 259:  * nonzero four-digit number are multiplied together in the context of
> 260:  * a {@code MathContext} object has a precision of three, the result

_has_ -> _having_

src/java.base/share/classes/java/math/BigDecimal.java line 275:

> 273:  * numerical values computed can differ if the exponent range of the
> 274:  * IEEE 754 format being approximated is exceeded since a {@code
> 275:  * MathContext} does not curtail the scale {@code BigDecimal}

_the scale_ -> _the scale of_

Suggest using another word than _curtail_, whose meaning will not be immediately clear to non-native readers as it's not a technical term.

src/java.base/share/classes/java/math/BigDecimal.java line 277:

> 275:  * MathContext} does not curtail the scale {@code BigDecimal}
> 276:  * results. Operations that would generate a NaN or exact infinity,
> 277:  * such as dividing by zero, throw an {@code Arithmetic-Exception} in

`Arithmetic-Exception` -> `ArithmeticException`

-------------

PR: https://git.openjdk.java.net/jdk/pull/2868