Rollup merge of rust-lang#72720 - poliorcetics:clarify-take-doc, r=joshtriplett

Clarify the documentation of `take`

This PR addresses the concerns of rust-lang#61222, adding an example for the behaviour of `Iterator::take` when there are less than `n` elements.

Author: JohnTitor

Diff for: src/libcore/iter/traits/iterator.rs

@@ -1180,6 +1180,17 @@ pub trait Iterator {
     /// assert_eq!(iter.next(), Some(2));
     /// assert_eq!(iter.next(), None);
     /// ```
+    ///
+    /// If less than `n` elements are available,
+    /// `take` will limit itself to the size of the underlying iterator:
+    ///
+    /// ```
+    /// let v = vec![1, 2];
+    /// let mut iter = v.into_iter().take(5);
+    /// assert_eq!(iter.next(), Some(1));
+    /// assert_eq!(iter.next(), Some(2));
+    /// assert_eq!(iter.next(), None);
+    /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     fn take(self, n: usize) -> Take<Self>