Skip to content

Commit

Permalink
Document workings of successors more clearly
Browse files Browse the repository at this point in the history
This is an attempt to fix rust-lang#135087 together with rust-lang#135886, but I am not sure if I've succeeded in adding much clarity here, so don't be shy with your comments.
  • Loading branch information
hkBst committed Mar 2, 2025
1 parent dee7d0e commit 6867806
Showing 1 changed file with 11 additions and 5 deletions.
16 changes: 11 additions & 5 deletions library/core/src/iter/sources/successors.rs
Original file line number Diff line number Diff line change
@@ -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;
Expand All @@ -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.
Expand Down

0 comments on commit 6867806

Please # to comment.