From c956fe5cea5c2221e54a98b6f83214b08eb5ce24 Mon Sep 17 00:00:00 2001
From: Jeff <dev@jeffa.io>
Date: Thu, 3 Mar 2022 19:45:53 -0500
Subject: [PATCH] Document new recommended use of method

---
 library/core/src/iter/traits/collect.rs | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/library/core/src/iter/traits/collect.rs b/library/core/src/iter/traits/collect.rs
index 637d7bc4488..9af3c0d4809 100644
--- a/library/core/src/iter/traits/collect.rs
+++ b/library/core/src/iter/traits/collect.rs
@@ -4,9 +4,11 @@
 /// created from an iterator. This is common for types which describe a
 /// collection of some kind.
 ///
-/// [`FromIterator::from_iter()`] is rarely called explicitly, and is instead
-/// used through [`Iterator::collect()`] method. See [`Iterator::collect()`]'s
-/// documentation for more examples.
+/// If you want to create a collection from the contents of an iterator, the
+/// [`Iterator::collect()`] method is preferred. However, the compiler is
+/// sometimes unable to infer the full type of the collection. In these cases,
+/// [`FromIterator::from_iter()`] can be more concise and readable. See the
+/// [`Iterator::collect()`] documentation for more examples of its use.
 ///
 /// See also: [`IntoIterator`].
 ///
@@ -32,6 +34,17 @@
 /// assert_eq!(v, vec![5, 5, 5, 5, 5]);
 /// ```
 ///
+/// Using [`FromIterator::from_iter()`] as a more readable alternative to
+/// [`Iterator::collect()`]:
+///
+/// ```
+/// # use std::collections::VecDeque;
+/// let first = (0..10).collect::<VecDeque<i32>>();
+/// let second = VecDeque::from_iter(0..10);
+///
+/// assert_eq!(first, second);
+/// ```
+///
 /// Implementing `FromIterator` for your type:
 ///
 /// ```