RFR: 8267939: Clarify the specification of iterator and spliterator forEachRemaining

[Paul Sandoz]

On Tue, 1 Jun 2021 23:37:10 GMT, Stuart Marks <smarks at openjdk.org> wrote:

>> Yeah, well spotted. I agree it's awkward. How about we lean on the behavior of the boxed counterpart:
>> 
>>     /**
>>      * Performs the given action for each remaining element until all elements
>>      * have been processed or the action throws an exception.  Actions are
>>      * performed in the order of iteration, if that order is specified.
>>      * <p>
>>      * This primitive-based method conforms to the same behavior as its
>>      * boxed counterpart with regards to the action's behavior.
>> ?
>
> Referring to the "boxed counterpart" is a bit too oblique, I think. The specification of Iterator itself isn't all that good to begin with. It's written as if the only possible source of an Iterator is a collection (which might have been true at first, but it isn't true any longer). But the rest of the Iterator spec refers to "the collection" so it kind of makes sense in that context.
> 
> Maybe just making a minimal change from "collection" to "source of elements" would make the most sense.
> 
>      * The behavior of an iterator is unspecified if the action modifies the source of
>      * elements in any way (even by calling the {@link #remove remove} method

Ok, that works for me.

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

PR: https://git.openjdk.java.net/jdk/pull/4290