doc: clearer and more correct Iterator::scan

[gthb]

The Iterator::scan documentation seemed a little misleading to my newcomer
eyes, and this tries to address that.

• I found “similar to fold” unhelpful because (a) the similarity is only that
  they maintain state between iterations, and (b) the dissimilarity is no less
  important: one returns a final value and the other an iterator. So this
  replaces that with “which, like fold, holds internal state, but unlike
  fold, produces a new iterator.

• I found “the return value from the closure, an Option, is yielded by the
  iterator” to be downright incorrect, because “yielded by the iterator” means
  “returned by the next method wrapped in Some”, so this implied that scan
  would convert an input iterator of T to an output iterator of Option<T>.
  So this replaces “yielded by the iterator” with “returned by the next
  method” and elaborates: “Thus the closure can return Some(value) to yield
  value, or None to end the iteration.”

• This also changes the example to illustrate the latter point by returning
  None to terminate the iteration early based on state.

[rustbot]

Hey! It looks like you've submitted a new PR for the library teams!

If this PR contains changes to any rust-lang/rust public library APIs then please comment with @rustbot label +T-libs-api -T-libs to tag it appropriately. If this PR contains changes to any unstable APIs please edit the PR description to add a link to the relevant API Change Proposal or create one if you haven't already. If you're unsure where your change falls no worries, just leave it as is and the reviewer will take a look and make a decision to forward on if necessary.

Examples of T-libs-api changes:

• Stabilizing library features
• Introducing insta-stable changes such as new implementations of existing stable traits on existing stable types
• Introducing new or changing existing unstable library APIs (excluding permanently unstable features / features without a tracking issue)
• Changing public documentation in ways that create new stability guarantees
• Changing observable runtime behavior of library APIs

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @m-ou-se (or someone else) soon.

Please see the contribution instructions for more information.

[gthb]

(Sidenote: this is my first Rust PR and the documentation, the x.py script, and the Github bot support, are all so nice! 👏)

[m-ou-se]

@bors r+

[bors]

📌 Commit 588592b has been approved by m-ou-se

It is now in the queue for this repository.

[bors]

⌛ Testing commit 588592b with merge bbdca4c...