RFR 8164691 Stream specification clarifications for iterate and collect

[Stuart Marks]

Hi Paul,

Overall looks good.

A couple minor wording comments. For the 3-arg collectors, the combiner arg is 
defined as

  * @param combiner an <a href="package-summary.html#Associativity">associative</a>,
  *                    <a 
href="package-summary.html#NonInterference">non-interfering</a>,
  *                    <a href="package-summary.html#Statelessness">stateless</a>
  *                    function that accepts two partial result containers and
  *                    merges them, which must be compatible with the accumulator
  *                    function.  The combiner function folds the elements in
  *                    result container that is the second argument into the
  *                    result container that is the first argument.

I'd suggest replacing the last sentence with

     The combiner function must fold the elements from the second
     result container into the first result container.

I think it's implicitly pretty clear that the first and second result containers 
are the first and second arguments to the combiner function.

If you're ok with the "must fold" style, then maybe also update the accumulator 
arg spec

  * @param accumulator an <a 
href="package-summary.html#Associativity">associative</a>,
  *                    <a 
href="package-summary.html#NonInterference">non-interfering</a>,
  *                    <a href="package-summary.html#Statelessness">stateless</a>
  *                    function that folds an element into a result container.

from "that folds" to "that must fold". That way all three args use the "must" 
style wording.

I think the same wording is present in all four Stream types.

s'marks


On 8/26/16 4:13 PM, Paul Sandoz wrote:
> Hi,
>
> Please review some minor tweaks to the stream specification:
>
>   http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8164691-stream-iterate-collect-spec-updates/webrev/index.html <http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8164691-stream-iterate-collect-spec-updates/webrev/index.html>
>
> The first tweak is to clarify the iterate methods and HB edges between function calls, the functions could potentially be stateful, they will never be called concurrently due to the nature of the source, but may be called in different threads.
>
> The second tweak is to the three-arg collect method. The combiner of result containers neglected to state how result containers should be merged.
>
> Thanks,
> Paul.
>