Rollup merge of #39174 - rspeer:iter-nth-doc-fix, r=alexcrichton

Fix a misleading statement in `Iterator.nth()`

The `Iterator.nth()` documentation says "Note that all preceding elements will be consumed". I assumed from that that the preceding elements would be the *only* ones that were consumed, but in fact the returned element is consumed as well.

The way I read the documentation, I assumed that `nth(0)` would not discard anything (there are 0 preceding elements, and maybe it just peeks at the start of the iterator somehow), so I added a sentence clarifying that it does. I also rephrased it to avoid the stunted "i.e." phrasing.

1 files changed, 5 insertions, 2 deletions

diff --git a/src/libcore/iter/iterator.rs b/src/libcore/iter/iterator.rs
index 3b406873d4b..d41767cce18 100644
--- a/src/libcore/iter/iterator.rs
+++ b/src/libcore/iter/iterator.rs
@@ -209,11 +209,14 @@ pub trait Iterator {
 
     /// Returns the `n`th element of the iterator.
     ///
-    /// Note that all preceding elements will be consumed (i.e. discarded).
-    ///
     /// Like most indexing operations, the count starts from zero, so `nth(0)`
     /// returns the first value, `nth(1)` the second, and so on.
     ///
+    /// Note that all preceding elements, as well as the returned element, will be
+    /// consumed from the iterator. That means that the preceding elements will be
+    /// discarded, and also that calling `nth(0)` multiple times on the same iterator
+    /// will return different elements.
+    ///
     /// `nth()` will return [`None`] if `n` is greater than or equal to the length of the
     /// iterator.
     ///