RFR 8164691 Stream specification clarifications for iterate and collect

[Paul Sandoz]

Thanks, updated in place,
Paul.

> On 26 Aug 2016, at 17:20, Stuart Marks <stuart.marks at oracle.com> wrote:
> 
> 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.
>>