Update iterator.dart to fully spec moveNext()

[jtlapp]

The moveNext docs should contain all the information necessary to implement it. There is otherwise no mention that this method is also used to set current to the initial element.

[googlebot]

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project (if not, look below for help). Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed (or fixed any issues), please reply here with @googlebot I signed it! and we'll verify it.

---

What to do if you already signed the CLA

Individual signers

• It's possible we don't have your GitHub username or you're using a different email address on your commit. Check your existing CLA data and verify that your email is set on your git commits.

Corporate signers

• Your company has a Point of Contact who decides which employees are authorized to participate. Ask your POC to be added to the group of authorized contributors. If you don't know who your Point of Contact is, direct the Google project maintainer to go/cla#troubleshoot (Public version).
• The email used to register you as an authorized contributor must be the email used for the Git commit. Check your existing CLA data and verify that your email is set on your git commits.
• The email used to register you as an authorized contributor must also be attached to your GitHub account.

ℹ️ Googlers: Go here for more info.

[jtlapp]

@googlebot I signed it!

[googlebot]

CLAs look good, thanks!

ℹ️ Googlers: Go here for more info.

[mit-mit]

Code review in https://dart-review.googlesource.com/c/sdk/+/127455

[lrhn]

This repeats the behavior mentioned in the class description, but it does make it easier to find this information while only having an Iterator typed variable available.

I'd prefer to phrase it slightly differently (we rarely use "invoke" in documentation, it's too formal). Maybe:

Use the [moveNext] method to move to the next element. This will change the
current value to that of the next element if there is a next element, which is when
[moveNext] returns true. Also use [moveNext] to start the iteration before accessing
the first element.

[lrhn]

Hmm, I misread this as a comment on current.

I'm not sure it's suitable as an addition on moveNext, because the documentation does say that already, but the existing text could probably be rewritten to express the same thing more clearly.

Maybe:

 /**
 * Advances the iterator to the next element of the iteration.
 * 
 * Should be called before reading [current]. It the call to `moveNext` returns
 * `true`, then [current] will contain the next element of the iteration until 
 * `moveNext` is called again. If the call returns `false`, there are no further
 * elements and [current] should not be used any more.
 *
 * It is safe to call [moveNext] after it has already returned `false`, 
 * but it must keep returning `false` and not have any other effect.
 *
 * A call to `moveNext` may throw for various reasons, including a concurrent change
 * to an underlying collection. If that happens, the iterator may be in an inconsistent 
 * state, and any further behavior of the iterator is unspecified, 
 * including the effect of reading [current]. 
 */

How does this read to you?

[mit-mit]

@jtlapp thanks for your contribution, and sorry the delay. Please see review feedback above.

[jtlapp]

I'm having trouble parsing your proposed alternatives. They aren't clear English. The moveNext docs should itself say what it does. Not having it there cost me time implementing it. This doesn't need to be complicated. Substitute "Call" for "Invoke" if you like. It is a concept all programmers know.

[lrhn]

If you have trouble parsing it, then it's probably not good documentation :).

The problem with describing what moveNext does is that all it does is to change internal state. As such, it's necessary to first describe the internal state (abstractly, because iterators can be implemented in many ways), and then say how calling moveNext updates that state.

So, maybe:

Advances the iterator to the next element of the iteration.

An iterator maintains a position in a sequence of elements being iterated.

The position starts out before the first element, and calls to moveNext advances the
position to the next element of the sequence, as long as there is a next element.
Returns true if there was a next element and the call advanced the position to that element,
and returns false if there are no further elements to iterate, and then the position
is after the last element.

The current elements of the iteration can be accessed as the [current] value after
a call to [moveNext] has returned true. It is not available before calling moveNext
the first time on an iterator, nor after such a call has returned false.

It is safe to call moveNext after it has already returned false,
but it must keep returning false and not have any other effect.

A call to moveNext may throw for various reasons, including a concurrent change
to an underlying collection. If that happens, the iterator may be in an inconsistent
state, and any further behavior of the iterator is unspecified,
including the effect of reading [current].

[jtlapp]

That looks fine to me. You put more care into the explanation than I did.

[mit-mit]

@jtlapp @lrhn I updated this PR with the docs comment I believe you both agreed to?