Fwd: JDK 9 RFR of JDK-8030942: Explicitly state floating-point summation requirements on non-finite inputs

[Joe Darcy]

Hello Georgiy,

On 7/25/2014 5:44 AM, Georgiy Rakov wrote:
>
> On 22.07.2014 20:12, Joe Darcy wrote:
>> Hello Georgiy,
>>
>> On 07/22/2014 08:49 AM, Georgiy Rakov wrote:
>>> Hello Joe,
>>>
>>> following assertion seems to me too loose:
>>>
>>>      * Because of the unspecified order of operations and the
>>>      * possibility of using differing summation schemes, the output of
>>>      * this method may vary on the same input values.
>>>
>>> as I see it this assertion imposes no constraints on how the sum can 
>>> be varied. Strictly speaking, I'm afraid from conformance point of 
>>> view it can cause the entire method to become untestable.
>>>
>>> Thank you,
>>> Georgiy.
>>>
>>
>> I would argue the statement above is just a clarification of the 
>> existing (non) specification of how the method can operate.
>>
>> Ideally, the sum method would state an error bound for its operation. 
>> There are bugs in this subcomponent mentioning adding such a bound, 
>> which may be done later in JDK 9.
>>
>> -Joe
> The sentence above and the following one actually say about 
> implementation details which couldn't be verified by conformance tests 
> - what is the order of summation, what is the summation scheme, 
> whether the result varies because of different summation scheme.
>
>      * <p> The value of a floating-point sum is a function both of the
>      * input values as well as the order of addition operations. The
>      * order of addition operations of this method is intentionally
>      * not defined to allow for implementation flexibility to improve
>      * the speed and accuracy of the computed result.
>
> What do you think about turning them into implementation notes? They 
> won't be normative in this case.
>
> But I'd like to say that following sentence I would leave as normative 
> since it talks about the condition which could be used in conformance 
> tests - "to reduce the error bound in the numerical sum compared to a 
> simple summation of {@code double} values".
>
>      * In particular, this method may be implemented using compensated
>      * summation or other technique to reduce the error bound in the
>      * numerical sum compared to a simple summation of {@code double}
>      * values.
>

The writers of conformance tests are not the sole consumers of the 
javadoc of Java SE nor are they even the primary consumers. Therefore, I 
do not think the text of the javadoc should be contorted so that all 
sentences that cannot be viewed as containing a testable assertion are 
banished to an @implnote.

The main text of the javadoc contains both normative and informative 
sentences. I don't plan further edits to the text in question for this bug.

Regards,

-Joe