src/share/classes/java/util/DoubleSummaryStatistics.java

@@ -1,7 +1,7 @@
 /*
- * 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
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.  Oracle designates this

@@ -127,13 +127,10 @@
 
     /**
      * 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
      * not defined to allow for implementation flexibility to improve
      * the speed and accuracy of the computed result.

@@ -141,10 +138,27 @@
      * 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.
      *
+     * <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.
      *
      * @return the sum of values, or zero if none
      */

@@ -191,20 +205,21 @@
 
     /**
      * 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.
      *
      * This method may be implemented using compensated summation or
      * 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.
      *
      * @return the arithmetic mean of values, or zero if none
      */