--- a/jdk/src/share/classes/java/util/DoubleSummaryStatistics.java	Wed Oct 09 12:13:31 2013 -0700
+++ b/jdk/src/share/classes/java/util/DoubleSummaryStatistics.java	Wed Oct 09 18:31:51 2013 -0700
@@ -111,12 +111,24 @@
 
     /**
      * Returns the sum of values recorded, or zero if no values have been
-     * recorded. The sum returned can vary depending upon the order in which
-     * values are recorded. This is due to accumulated rounding error in
-     * addition of values of differing magnitudes. Values sorted by increasing
-     * absolute magnitude tend to yield more accurate results.  If any recorded
-     * value is a {@code NaN} or the sum is at any point a {@code NaN} then the
-     * sum will be {@code NaN}.
+     * 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.
+     *
+     * 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.
+     *
+     * @apiNote Sorting values by increasing absolute magnitude tends to yield
+     * more accurate results.
      *
      * @return the sum of values, or zero if none
      */
@@ -153,13 +165,21 @@
     }
 
     /**
-     * Returns the arithmetic mean of values recorded, or zero if no values have been
-     * recorded. The average returned can vary depending upon the order in
-     * which values are recorded. This is due to accumulated rounding error in
-     * addition of values of differing magnitudes. Values sorted by increasing
-     * absolute magnitude tend to yield more accurate results. If any recorded
-     * value is a {@code NaN} or the sum is at any point a {@code NaN} then the
-     * average will be {@code NaN}.
+     * 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.
+     *
+     * @apiNote Values sorted by increasing absolute magnitude tend to yield
+     * more accurate results.
      *
      * @return the arithmetic mean of values, or zero if none
      */

--- a/jdk/src/share/classes/java/util/stream/DoubleStream.java	Wed Oct 09 12:13:31 2013 -0700
+++ b/jdk/src/share/classes/java/util/stream/DoubleStream.java	Wed Oct 09 18:31:51 2013 -0700
@@ -502,22 +502,42 @@
                   BiConsumer<R, R> combiner);
 
     /**
-     * Returns the sum of elements in this stream.  The sum returned can vary
-     * depending upon the order in which elements are encountered.  This is due
-     * to accumulated rounding error in addition of values of differing
-     * magnitudes. Elements sorted by increasing absolute magnitude tend to
-     * yield more accurate results.  If any stream element is a {@code NaN} or
-     * the sum is at any point a {@code NaN} then the sum will be {@code NaN}.
-     * This is a special case of a
-     * <a href="package-summary.html#Reduction">reduction</a> and is
+     * Returns the sum of elements in this stream.
+     *
+     * Summation is a special case of a <a
+     * href="package-summary.html#Reduction">reduction</a>. If
+     * floating-point summation were exact, this method would be
      * equivalent to:
+     *
      * <pre>{@code
      *     return reduce(0, Double::sum);
      * }</pre>
      *
+     * However, since floating-point summation is not exact, the above
+     * 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
+     * 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.
+     *
+     * 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>This is a <a href="package-summary.html#StreamOps">terminal
      * operation</a>.
      *
+     * @apiNote Sorting values by increasing absolute magnitude tends to yield
+     * more accurate results.
+     *
      * @return the sum of elements in this stream
      */
     double sum();
@@ -578,19 +598,29 @@
     long count();
 
     /**
-     * Returns an {@code OptionalDouble} describing the arithmetic mean of elements of
-     * this stream, or an empty optional if this stream is empty.  The average
-     * returned can vary depending upon the order in which elements are
-     * encountered. This is due to accumulated rounding error in addition of
-     * elements of differing magnitudes. Elements sorted by increasing absolute
-     * magnitude tend to yield more accurate results. If any recorded value is
-     * a {@code NaN} or the sum is at any point a {@code NaN} then the average
-     * will be {@code NaN}. This is a special case of a
-     * <a href="package-summary.html#Reduction">reduction</a>.
+     * Returns an {@code OptionalDouble} describing the arithmetic
+     * 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.
+     *
+     * This method may be implemented using compensated summation or
+     * other technique to reduce the error bound in the {@link #sum
+     * numerical sum} used to compute the average.
+     *
+     *  <p>The average is a special case of a <a
+     *  href="package-summary.html#Reduction">reduction</a>.
      *
      * <p>This is a <a href="package-summary.html#StreamOps">terminal
      * operation</a>.
      *
+     * @apiNote Elements sorted by increasing absolute magnitude tend
+     * to yield more accurate results.
+     *
      * @return an {@code OptionalDouble} containing the average element of this
      * stream, or an empty optional if the stream is empty
      */