Refactor macro comment and add resize with zeros example

diff --git a/src/liballoc/vec.rs b/src/liballoc/vec.rs
index 3188de512662c9290deafc77bc3b39fbdc4d3f75..f7a0bbdceafc93325359fbb83a51b413548db0da 100644 (file)
--- a/src/liballoc/vec.rs
+++ b/src/liballoc/vec.rs
@@ -121,12 +121,16 @@
 /// ```
 ///
 /// It can also initialize each element of a `Vec<T>` with a given value.
-/// Initializing a `Vec<T>` in this manner is the most efficient and safest way to allocate a
-/// vector of zeros as previously zeroed memory is requested from the operating system:
+/// This may be more efficient than performing allocation and initialization
+/// in separate steps, especially when initializing a vector of zeros:
 ///
 /// ```
 /// let vec = vec![0; 5];
 /// assert_eq!(vec, [0, 0, 0, 0, 0]);
+///
+/// // The following is equivalent, but potentially slower:
+/// let mut vec1 = Vec::with_capacity(5);
+/// vec1.resize(5, 0);
 /// ```
 ///
 /// Use a `Vec<T>` as an efficient stack: