RFR: 8261366: Add discussion of IEEE 754 to BigDecimal

[Joe Darcy]

Thanks for the review Florent; will fix in the next push,

-Joe

On 3/8/2021 1:57 AM, Florent Guillaume wrote:
> 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