Rollup merge of #135895 - hkBst:patch-15, r=joboet

Document workings of successors more clearly

This is an attempt to fix #135087 together with https://github.com/rust-lang/rust/pull/135886, but I am not sure if I've succeeded in adding much clarity here, so don't be shy with your comments.

1 files changed, 11 insertions, 5 deletions

diff --git a/library/core/src/iter/sources/successors.rs b/library/core/src/iter/sources/successors.rs
index e14c9235e55..5466131903f 100644
--- a/library/core/src/iter/sources/successors.rs
+++ b/library/core/src/iter/sources/successors.rs
@@ -1,11 +1,16 @@
 use crate::fmt;
 use crate::iter::FusedIterator;
 
-/// Creates a new iterator where each successive item is computed based on the preceding one.
+/// Creates an iterator which, starting from an initial item,
+/// computes each successive item from the preceding one.
 ///
-/// The iterator starts with the given first item (if any)
-/// and calls the given `FnMut(&T) -> Option<T>` closure to compute each item’s successor.
-/// The iterator will yield the `T`s returned from the closure.
+/// This iterator stores an optional item (`Option<T>`) and a successor closure (`impl FnMut(&T) -> Option<T>`).
+/// Its `next` method returns the stored optional item and
+/// if it is `Some(val)` calls the stored closure on `&val` to compute and store its successor.
+/// The iterator will apply the closure successively to the stored option's value until the option is `None`.
+/// This also means that once the stored option is `None` it will remain `None`,
+/// as the closure will not be called again, so the created iterator is a [`FusedIterator`].
+/// The iterator's items will be the initial item and all of its successors as calculated by the successor closure.
 ///
 /// ```
 /// use std::iter::successors;
@@ -24,7 +29,8 @@ where
     Successors { next: first, succ }
 }
 
-/// A new iterator where each successive item is computed based on the preceding one.
+/// An iterator which, starting from an initial item,
+/// computes each successive item from the preceding one.
 ///
 /// This `struct` is created by the [`iter::successors()`] function.
 /// See its documentation for more.