> On 17 May 2016, at 23:15, Claes Redestad <claes.redes...@oracle.com> wrote:
>
> Hi,
>
> the first block in Stream.java bothers me:
>
> + * <p>A stream implementation is permitted significant latitude in optimizing
> + * the computation of the result. For example, a stream implementation is
> free
> + * to elide operations (or entire stages) from a stream pipeline -- and
> + * therefore elide invocation of behavioral parameters -- if it can prove
> that
> + * it would not affect the result of the computation. This means, that unless
> + * otherwise specified (such as by the terminal operations {@code forEach}
> and
> + * {@code forEachOrdered}), that side-effects of behavioral parameters may
> not
> + * always be executed and should not be relied upon. (For a specific example
> of
> + * such an optimization, see the API note documented on the {@link #count}
> + * operation. For more detail, see the
> + * <a href="package-summary.html#SideEffects">side-effects</a> section of the
> + * strean package documentation.)
> + *
>
>
> The first sentence in particular is hard to read and interpret, and after
> reading it twice I'm not sure if it's entirely redundant or if you need to
> better specify what other freedoms are given to a stream implementation?
>
The first sentence is setting the stage that it is the result and not the
computation that is key and we want to get across that this is not a limitation
but a feature, since streams are about specifying a computation declaratively
(and if side-effects are present then watch out!).
We cannot specify the degrees of freedom, we can only specify the result be the
same. Perhaps the "For example, “ in the following sentence can be removed or
replaced with “As such ….” ?
> How about this:
>
> + * <p>Astream implementation is free to elide operations (or entire stages)
> + * from a stream pipeline -- andtherefore elide invocation of behavioral + *
> parameters -- if it can prove that it would not affect the result of the + *
> computation. This means that side-effects of behavioral parameters may not +
> * always be executed and should not be relied upon, unless otherwise
> specified + * (such as by the terminal operations {@code forEach} and
> + * {@code forEachOrdered}).(For a specific example ofsuch an optimization, +
> * see the API note documented on the {@link #count} operation. For more + *
> details, see the <a href="package-summary.html#SideEffects">side-effects</a>
> + * section of the stream package documentation.)
> + *
>
I like the move of the “unless …” to the end of the sentence, that reads better.
Thanks,
Paul.
