Rollup merge of #69213 - LeSeulArtichaut:improve-doc-iter, r=steveklabnik

Improve documentation on iterators length

Attempts to resolve #66491. @the8472 does this help?

r? @steveklabnik

2 files changed, 5 insertions, 2 deletions

diff --git a/src/libcore/iter/mod.rs b/src/libcore/iter/mod.rs
index 5fa9962f811..080b70c6368 100644
--- a/src/libcore/iter/mod.rs
+++ b/src/libcore/iter/mod.rs
@@ -43,7 +43,7 @@
 //! are elements, and once they've all been exhausted, will return `None` to
 //! indicate that iteration is finished. Individual iterators may choose to
 //! resume iteration, and so calling [`next`] again may or may not eventually
-//! start returning `Some(Item)` again at some point.
+//! start returning `Some(Item)` again at some point (for example, see [`TryIter`]).
 //!
 //! [`Iterator`]'s full definition includes a number of other methods as well,
 //! but they are default methods, built on top of [`next`], and so you get
@@ -56,6 +56,7 @@
 //! [`Iterator`]: trait.Iterator.html
 //! [`next`]: trait.Iterator.html#tymethod.next
 //! [`Option`]: ../../std/option/enum.Option.html
+//! [`TryIter`]: ../../std/sync/mpsc/struct.TryIter.html
 //!
 //! # The three forms of iteration
 //!
diff --git a/src/libcore/iter/traits/exact_size.rs b/src/libcore/iter/traits/exact_size.rs
index 4a7db348b18..ad87d09588e 100644
--- a/src/libcore/iter/traits/exact_size.rs
+++ b/src/libcore/iter/traits/exact_size.rs
@@ -69,8 +69,10 @@
 /// ```
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait ExactSizeIterator: Iterator {
-    /// Returns the exact number of times the iterator will iterate.
+    /// Returns the exact length of the iterator.
     ///
+    /// The implementation ensures that the iterator will return exactly `len()`
+    /// more times a `Some(T)` value, before returning `None`.
     /// This method has a default implementation, so you usually should not
     /// implement it directly. However, if you can provide a more efficient
     /// implementation, you can do so. See the [trait-level] docs for an