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

[Joe Darcy]

Hello,

Please review my changes to address:

     JDK-8030942: Explicitly state floating-point summation requirements 
on non-finite inputs
     http://cr.openjdk.java.net/~darcy/8030942.0/

Patch below.

Thanks,

-Joe

--- old/src/share/classes/java/util/DoubleSummaryStatistics.java 
2014-07-15 17:26:41.000000000 -0700
+++ new/src/share/classes/java/util/DoubleSummaryStatistics.java 
2014-07-15 17:26:41.000000000 -0700
@@ -1,5 +1,5 @@
  /*
- * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights 
reserved.
+ * Copyright (c) 2012, 2014, Oracle and/or its affiliates. All rights 
reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
@@ -129,9 +129,6 @@
       * Returns the sum of values recorded, or zero if no values have been
       * recorded.
       *
-     * If any recorded value is a NaN or the sum is at any point a NaN
-     * then the sum will be NaN.
-     *
       * <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
@@ -143,6 +140,23 @@
       * numerical sum compared to a simple summation of {@code double}
       * values.
       *
+     * <p>If any recorded value is a NaN or the intermediate sum is at
+     * any point a NaN, then the final sum will be NaN.
+     *
+     * If the recorded values contain infinities of opposite sign, the
+     * final sum will be NaN.
+     *
+     * It is possible for intermediate sums of finite values to
+     * overflow into opposite-signed infinities; if that occurs, the
+     * final sum will be NaN even if the recorded values are all
+     * finite.
+     *
+     * If the exact sum is infinite, a properly-signed infinity is
+     * returned.
+     *
+     * If all the recorded values are zero, the sign of zero is
+     * <em>not</em> guaranteed to be preserved in the final sum.
+     *
       * @apiNote Values sorted by increasing absolute magnitude tend to 
yield
       * more accurate results.
       *
@@ -193,9 +207,6 @@
       * Returns the arithmetic mean of values recorded, or zero if no
       * values have been recorded.
       *
-     * If any recorded value is a NaN or the sum is at any point a NaN
-     * then the average will be code NaN.
-     *
       * <p>The average returned can vary depending upon the order in
       * which values are recorded.
       *
@@ -203,6 +214,10 @@
       * other technique to reduce the error bound in the {@link #getSum
       * numerical sum} used to compute the average.
       *
+     * <p>This method can return a NaN or infinite result in the same
+     * kind of numerical situations as {@linkplain #getSum() the sum}
+     * can be NaN or infinite, respectively.
+     *
       * @apiNote Values sorted by increasing absolute magnitude tend to 
yield
       * more accurate results.
       *
--- old/src/share/classes/java/util/stream/DoubleStream.java 2014-07-15 
17:26:42.000000000 -0700
+++ new/src/share/classes/java/util/stream/DoubleStream.java 2014-07-15 
17:26:42.000000000 -0700
@@ -1,5 +1,5 @@
  /*
- * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights 
reserved.
+ * Copyright (c) 2012, 2014, Oracle and/or its affiliates. All rights 
reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
@@ -470,10 +470,7 @@
       * code is not necessarily equivalent to the summation computation
       * done by this method.
       *
-     * <p>If any stream element is a NaN or the sum is at any point a NaN
-     * then the sum will be NaN.
-     *
-     * The value of a floating-point sum is a function both
+     * <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
@@ -485,6 +482,23 @@
       * numerical sum compared to a simple summation of {@code double}
       * values.
       *
+     * <p>If any stream element is a NaN or the intermediate sum is at
+     * any point a NaN, then the final sum will be NaN.
+     *
+     * If the stream elements contain infinities of opposite sign, the
+     * final sum will be NaN.
+     *
+     * It is possible for intermediate sums of finite values to
+     * overflow into opposite-signed infinities; if that occurs, the
+     * final sum will be NaN even if the stream elements are all
+     * finite.
+     *
+     * If the exact sum is infinite, a properly-signed infinity is
+     * returned.
+     *
+     * If all the stream elements are zero, the sign of zero is
+     * <em>not</em> guaranteed to be preserved in the final sum.
+     *
       * <p>This is a <a href="package-summary.html#StreamOps">terminal
       * operation</a>.
       *
@@ -555,9 +569,6 @@
       * mean of elements of this stream, or an empty optional if this
       * stream is empty.
       *
-     * If any recorded value is a NaN or the sum is at any point a NaN
-     * then the average will be NaN.
-     *
       * <p>The average returned can vary depending upon the order in
       * which values are recorded.
       *
@@ -565,6 +576,10 @@
       * other technique to reduce the error bound in the {@link #sum
       * numerical sum} used to compute the average.
       *
+     * <p>This method can return a NaN or infinite result in the same
+     * kind of numerical situations as {@linkplain #sum() the sum} can
+     * be NaN or infinite, respectively.
+     *
       *  <p>The average is a special case of a <a
       * href="package-summary.html#Reduction">reduction</a>.
       *