--- a/jdk/src/java.base/share/classes/java/util/stream/DoubleStream.java	Thu May 19 21:59:35 2016 -0700
+++ b/jdk/src/java.base/share/classes/java/util/stream/DoubleStream.java	Fri May 20 11:47:39 2016 +0200
@@ -211,6 +211,11 @@
      *         .sum();
      * }</pre>
      *
+     * <p>In cases where stream implementation is able to optimize away the
+     * production of some or all the elements (such as with short-circuiting
+     * operations like {@code findFirst}, or in the example described in
+     * {@link #count}), the action will not be invoked for those elements.
+     *
      * @param action a <a href="package-summary.html#NonInterference">
      *               non-interfering</a> action to perform on the elements as
      *               they are consumed from the stream