RFR: 8279361: Error in documentation of third Stream.reduce method

[Viktor Klang]

On Fri, 30 Sep 2022 00:44:01 GMT, Stuart Marks <smarks at openjdk.org> wrote:

>> This JavaDoc change attempts to shine some light on the `combiner`-function as it relates to the third variant of `Stream.reduce` since it according to the bug submission in JBS can be confusing that the `combiner` is not mentioned in the code example in the documentation.
>
> One of the problems with pseudo-code is that people can interpret it too literally. Even though we say things like "the result is as if..." it still invites confusion. For example, the proposed chunk code invokes the combiner even in the case where there is only one chunk. However, the clause that follows says:
> 
>> In the case where there are less than two chunks, invoking the
>> combiner is not needed as there is no merging to be done.
> 
> seems to be quasi-normative in that it implies (or does it?) that the combiner _won't_ be called if there is only a single chunk. While that's true of the current implementation, the current spec doesn't guarantee it, and I don't think we want to add such a requirement even though it might be desirable. (At least, we shouldn't add a requirement without good reason.)
> 
> So there's still a question of whether or not the combiner is called in sequential cases, and also about its fundamental role in the reduce operation. I've answered a couple Stack Overflow questions on it:
> 
> https://stackoverflow.com/questions/24308146/why-is-a-combiner-needed-for-reduce-method-that-converts-type-in-java-8/24316429#24316429
> 
> https://stackoverflow.com/questions/29210176/can-a-collectors-combiner-function-ever-be-used-on-sequential-streams/29295055#29295055
> 
> (And maybe @amaembo has too. And yes Tagir we're still thinking about ordered reduce or fold operations.)
> 
> So maybe a prose description of the splitting and combining process would be preferable. Or possibly a more-pseudo pseudo-code example that doesn't have as much detail, so people don't read into it so much.

@stuart-marks 

Since there is no contract requiring the use of the `combiner`, all the documentation can say is that "it will be used if the implementation needs it"—which still doesn't answer (deterministically) *when* it will be applied, as even in the parallel case, presuming that the source is small enough not to warrant more than one chunk.

I've taken a couple of stabs at trying to word this in a clear manner, but to be honest, perhaps the most confusion-reducing action is to delete the pseudocode altogether? 🤔

-------------

PR: https://git.openjdk.org/jdk/pull/10469