Rollup merge of rust-lang#135118 - ranger-ross:better-docs-on-iter-fns, r=jhpratt

Clarified the documentation on `core::iter::from_fn` and `core::iter::successors`

This PR clarifies the closure requirements for `core::iter::from_fn` and `core::iter::successors`.

`std::iter::successors` in particular is a bit difficult to understand if you are not already familiar with the signature of [`checked_mul`](https://docs.rs/num/latest/num/trait.CheckedMul.html) used in the example.

See rust-lang#135087

Author: jhpratt

Diff for: library/core/src/iter/sources/from_fn.rs

@@ -3,6 +3,8 @@ use crate::fmt;
 /// Creates a new iterator where each iteration calls the provided closure
 /// `F: FnMut() -> Option<T>`.
 ///
+/// The iterator will yield the `T`s returned from the closure.
+///
 /// This allows creating a custom iterator with any behavior
 /// without using the more verbose syntax of creating a dedicated type
 /// and implementing the [`Iterator`] trait for it.

Diff for: library/core/src/iter/sources/successors.rs

@@ -5,6 +5,7 @@ use crate::iter::FusedIterator;
 ///
 /// 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.
 ///
 /// ```
 /// use std::iter::successors;