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 (as there are 0 preceding elements), so I added a sentence clarifying that it does. I also rephrased it to avoid the stunted "i.e." phrasing.

1 files changed, 4 insertions, 1 deletions

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