8130023: API java.util.stream: explicitly specify guaranteed execution of the pipeline

Reviewed-by: briangoetz, redestad

jdk/src/java.base/share/classes/java/util/stream/IntStream.java

@@ -209,6 +209,11 @@ public interface IntStream extends BaseStream<Integer, IntStream> {
      *         .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