From: Kornel <kornel@geekhood.net>
Date: Thu, 18 Mar 2021 18:43:08 +0000 (+0000)
Subject: Expand documentation of Iterator::take and skip
X-Git-Url: https://git.lizzy.rs/?a=commitdiff_plain;h=6cfdc385a1e3e9dd624ce87c75f25f1bb16118a1;p=rust.git

Expand documentation of Iterator::take and skip
---

diff --git a/library/core/src/iter/traits/iterator.rs b/library/core/src/iter/traits/iterator.rs
index f8504e842ee..4c603994647 100644
--- a/library/core/src/iter/traits/iterator.rs
+++ b/library/core/src/iter/traits/iterator.rs
@@ -1228,7 +1228,11 @@ fn map_while<B, P>(self, predicate: P) -> MapWhile<Self, P>
 
     /// Creates an iterator that skips the first `n` elements.
     ///
-    /// After they have been consumed, the rest of the elements are yielded.
+    /// `skip(n)` skips elements until `n` elements are skipped or the end of the
+    /// iterator is reached (whichever happens first). After that, all the remaining
+    /// elements are yielded. In particular, if the original iterator is too short,
+    /// then the returned iterator is empty.
+    ///
     /// Rather than overriding this method directly, instead override the `nth` method.
     ///
     /// # Examples
@@ -1252,7 +1256,14 @@ fn skip(self, n: usize) -> Skip<Self>
         Skip::new(self, n)
     }
 
-    /// Creates an iterator that yields its first `n` elements.
+    /// Creates an iterator that yields the first `n` elements, or fewer
+    /// if the underlying iterator ends sooner.
+    ///
+    /// `take(n)` yields elements until `n` elements are yielded or the end of
+    /// the iterator is reached (whichever happens first).
+    /// The returned iterator is a prefix of length `n` if the original iterator
+    /// contains at least `n` elements, otherwise it contains all of the
+    /// (fewer than `n`) elements of the original iterator.
     ///
     /// # Examples
     ///