Rollup merge of #99244 - gthb:doc-improve-iterator-scan, r=m-ou-se

doc: clearer and more correct Iterator::scan

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`.

0 files changed, 0 insertions, 0 deletions