Improve docs for std::vec

1 files changed, 105 insertions, 74 deletions

diff --git a/src/libcollections/vec.rs b/src/libcollections/vec.rs
index 932366d77ad..866147b1409 100644
--- a/src/libcollections/vec.rs
+++ b/src/libcollections/vec.rs
@@ -11,6 +11,38 @@
 //! A growable list type, written `Vec<T>` but pronounced 'vector.'
 //!
 //! Vectors have `O(1)` indexing, push (to the end) and pop (from the end).
+//!
+//! # Examples
+//!
+//! Explicitly creating a `Vec<T>` with `new()`:
+//!
+//! ```
+//! let xs: Vec<i32> = Vec::new();
+//! ```
+//!
+//! Using the `vec!` macro:
+//!
+//! ```
+//! let ys: Vec<i32> = vec![];
+//!
+//! let zs = vec![1i32, 2, 3, 4, 5];
+//! ```
+//!
+//! Push:
+//!
+//! ```
+//! let mut xs = vec![1i32, 2];
+//!
+//! xs.push(3);
+//! ```
+//!
+//! And pop:
+//!
+//! ```
+//! let mut xs = vec![1i32, 2];
+//!
+//! let two = xs.pop();
+//! ```
 
 use core::prelude::*;
 
@@ -31,7 +63,7 @@ use core::uint;
 
 use slice::CloneSliceExt;
 
-/// An owned, growable vector.
+/// A growable list type, written `Vec<T>` but pronounced 'vector.'
 ///
 /// # Examples
 ///
@@ -65,7 +97,7 @@ use slice::CloneSliceExt;
 /// assert_eq!(vec, vec![1, 2, 3, 4]);
 /// ```
 ///
-/// Use a `Vec` as an efficient stack:
+/// Use a `Vec<T>` as an efficient stack:
 ///
 /// ```
 /// let mut stack = Vec::new();
@@ -86,20 +118,17 @@ use slice::CloneSliceExt;
 ///
 /// # Capacity and reallocation
 ///
-/// The capacity of a vector is the amount of space allocated for any future
-/// elements that will be added onto the vector. This is not to be confused
-/// with the *length* of a vector, which specifies the number of actual
-/// elements within the vector. If a vector's length exceeds its capacity,
-/// its capacity will automatically be increased, but its elements will
-/// have to be reallocated.
+/// The capacity of a vector is the amount of space allocated for any future elements that will be
+/// added onto the vector. This is not to be confused with the *length* of a vector, which
+/// specifies the number of actual elements within the vector. If a vector's length exceeds its
+/// capacity, its capacity will automatically be increased, but its elements will have to be
+/// reallocated.
 ///
-/// For example, a vector with capacity 10 and length 0 would be an empty
-/// vector with space for 10 more elements. Pushing 10 or fewer elements onto
-/// the vector will not change its capacity or cause reallocation to occur.
-/// However, if the vector's length is increased to 11, it will have to
-/// reallocate, which can be slow. For this reason, it is recommended
-/// to use `Vec::with_capacity` whenever possible to specify how big the vector
-/// is expected to get.
+/// For example, a vector with capacity 10 and length 0 would be an empty vector with space for 10
+/// more elements. Pushing 10 or fewer elements onto the vector will not change its capacity or
+/// cause reallocation to occur. However, if the vector's length is increased to 11, it will have
+/// to reallocate, which can be slow. For this reason, it is recommended to use
+/// `Vec::with_capacity` whenever possible to specify how big the vector is expected to get.
 #[unsafe_no_drop_flag]
 #[stable]
 pub struct Vec<T> {
@@ -130,7 +159,7 @@ impl<'a, T> IntoCow<'a, Vec<T>, [T]> for &'a [T] where T: Clone {
 }
 
 impl<T> Vec<T> {
-    /// Constructs a new, empty `Vec`.
+    /// Constructs a new, empty `Vec<T>`.
     ///
     /// The vector will not allocate until elements are pushed onto it.
     ///
@@ -149,16 +178,15 @@ impl<T> Vec<T> {
         Vec { ptr: EMPTY as *mut T, len: 0, cap: 0 }
     }
 
-    /// Constructs a new, empty `Vec` with the specified capacity.
+    /// Constructs a new, empty `Vec<T>` with the specified capacity.
     ///
-    /// The vector will be able to hold exactly `capacity` elements without
-    /// reallocating. If `capacity` is 0, the vector will not allocate.
+    /// The vector will be able to hold exactly `capacity` elements without reallocating. If
+    /// `capacity` is 0, the vector will not allocate.
     ///
-    /// It is important to note that this function does not specify the
-    /// *length* of the returned vector, but only the *capacity*. (For an
-    /// explanation of the difference between length and capacity, see
-    /// the main `Vec` docs above, 'Capacity and reallocation'.) To create
-    /// a vector of a given length, use `Vec::from_elem` or `Vec::from_fn`.
+    /// It is important to note that this function does not specify the *length* of the returned
+    /// vector, but only the *capacity*. (For an explanation of the difference between length and
+    /// capacity, see the main `Vec<T>` docs above, 'Capacity and reallocation'.) To create a
+    /// vector of a given length, use `Vec::from_elem` or `Vec::from_fn`.
     ///
     /// # Examples
     ///
@@ -192,10 +220,10 @@ impl<T> Vec<T> {
         }
     }
 
-    /// Creates and initializes a `Vec`.
+    /// Creates and initializes a `Vec<T>`.
     ///
-    /// Creates a `Vec` of size `length` and initializes the elements to the
-    /// value returned by the closure `op`.
+    /// Creates a `Vec<T>` of size `length` and initializes the elements to the value returned by
+    /// the closure `op`.
     ///
     /// # Examples
     ///
@@ -260,10 +288,9 @@ impl<T> Vec<T> {
 
     /// Creates a vector by copying the elements from a raw pointer.
     ///
-    /// This function will copy `elts` contiguous elements starting at `ptr`
-    /// into a new allocation owned by the returned `Vec`. The elements of the
-    /// buffer are copied into the vector without cloning, as if `ptr::read()`
-    /// were called on them.
+    /// This function will copy `elts` contiguous elements starting at `ptr` into a new allocation
+    /// owned by the returned `Vec<T>`. The elements of the buffer are copied into the vector
+    /// without cloning, as if `ptr::read()` were called on them.
     #[inline]
     #[unstable = "just renamed from raw::from_buf"]
     pub unsafe fn from_raw_buf(ptr: *const T, elts: uint) -> Vec<T> {
@@ -273,11 +300,10 @@ impl<T> Vec<T> {
         dst
     }
 
-    /// Consumes the `Vec`, partitioning it based on a predicate.
+    /// Consumes the `Vec<T>`, partitioning it based on a predicate.
     ///
-    /// Partitions the `Vec` into two `Vec`s `(A,B)`, where all elements of `A`
-    /// satisfy `f` and all elements of `B` do not. The order of elements is
-    /// preserved.
+    /// Partitions the `Vec<T>` into two `Vec<T>`s `(A,B)`, where all elements of `A` satisfy `f`
+    /// and all elements of `B` do not. The order of elements is preserved.
     ///
     /// # Examples
     ///
@@ -306,9 +332,9 @@ impl<T> Vec<T> {
 }
 
 impl<T: Clone> Vec<T> {
-    /// Constructs a `Vec` with copies of a value.
+    /// Constructs a `Vec<T>` with copies of a value.
     ///
-    /// Creates a `Vec` with `length` copies of `value`.
+    /// Creates a `Vec<T>` with `length` copies of `value`.
     ///
     /// # Examples
     ///
@@ -331,10 +357,10 @@ impl<T: Clone> Vec<T> {
         }
     }
 
-    /// Appends all elements in a slice to the `Vec`.
+    /// Appends all elements in a slice to the `Vec<T>`.
     ///
     /// Iterates over the slice `other`, clones each element, and then appends
-    /// it to this `Vec`. The `other` vector is traversed in-order.
+    /// it to this `Vec<T>`. The `other` vector is traversed in-order.
     ///
     /// # Examples
     ///
@@ -363,9 +389,9 @@ impl<T: Clone> Vec<T> {
         }
     }
 
-    /// Grows the `Vec` in-place.
+    /// Grows the `Vec<T>` in-place.
     ///
-    /// Adds `n` copies of `value` to the `Vec`.
+    /// Adds `n` copies of `value` to the `Vec<T>`.
     ///
     /// # Examples
     ///
@@ -387,7 +413,7 @@ impl<T: Clone> Vec<T> {
 
     /// Partitions a vector based on a predicate.
     ///
-    /// Clones the elements of the vector, partitioning them into two `Vec`s
+    /// Clones the elements of the vector, partitioning them into two `Vec<T>`s
     /// `(a, b)`, where all elements of `a` satisfy `f` and all elements of `b`
     /// do not. The order of elements is preserved.
     ///
@@ -639,8 +665,7 @@ unsafe fn dealloc<T>(ptr: *mut T, len: uint) {
 }
 
 impl<T> Vec<T> {
-    /// Returns the number of elements the vector can hold without
-    /// reallocating.
+    /// Returns the number of elements the vector can hold without reallocating.
     ///
     /// # Examples
     ///
@@ -661,7 +686,7 @@ impl<T> Vec<T> {
     }
 
     /// Reserves capacity for at least `additional` more elements to be inserted in the given
-    /// `Vec`. The collection may reserve more space to avoid frequent reallocations.
+    /// `Vec<T>`. The collection may reserve more space to avoid frequent reallocations.
     ///
     /// # Panics
     ///
@@ -695,7 +720,7 @@ impl<T> Vec<T> {
     }
 
     /// Reserves the minimum capacity for exactly `additional` more elements to be inserted in the
-    /// given `Vec`. Does nothing if the capacity is already sufficient.
+    /// given `Vec<T>`. Does nothing if the capacity is already sufficient.
     ///
     /// Note that the allocator may give the collection more space than it requests. Therefore
     /// capacity can not be relied upon to be precisely minimal. Prefer `reserve` if future
@@ -722,16 +747,19 @@ impl<T> Vec<T> {
         }
     }
 
-    /// Shrinks the capacity of the vector as much as possible. It will drop
-    /// down as close as possible to the length but the allocator may still
-    /// inform the vector that there is space for a few more elements.
+    /// Shrinks the capacity of the vector as much as possible.
+    ///
+    /// It will drop down as close as possible to the length but the allocator may still inform the
+    /// vector that there is space for a few more elements.
     ///
     /// # Examples
     ///
     /// ```
     /// let mut vec: Vec<int> = Vec::with_capacity(10);
+    ///
     /// vec.push_all(&[1, 2, 3]);
     /// assert_eq!(vec.capacity(), 10);
+    ///
     /// vec.shrink_to_fit();
     /// assert!(vec.capacity() >= 3);
     /// ```
@@ -820,14 +848,14 @@ impl<T> Vec<T> {
         }
     }
 
-    /// Creates a consuming iterator, that is, one that moves each
-    /// value out of the vector (from start to end). The vector cannot
-    /// be used after calling this.
+    /// Creates a consuming iterator, that is, one that moves each value out of the vector (from
+    /// start to end). The vector cannot be used after calling this.
     ///
     /// # Examples
     ///
     /// ```
     /// let v = vec!["a".to_string(), "b".to_string()];
+    ///
     /// for s in v.into_iter() {
     ///     // s has type String, not &String
     ///     println!("{}", s);
@@ -852,9 +880,8 @@ impl<T> Vec<T> {
 
     /// Sets the length of a vector.
     ///
-    /// This will explicitly set the size of the vector, without actually
-    /// modifying its buffers, so it is up to the caller to ensure that the
-    /// vector is actually the specified size.
+    /// This will explicitly set the size of the vector, without actually modifying its buffers, so
+    /// it is up to the caller to ensure that the vector is actually the specified size.
     ///
     /// # Examples
     ///
@@ -870,8 +897,10 @@ impl<T> Vec<T> {
         self.len = len;
     }
 
-    /// Removes an element from anywhere in the vector and return it, replacing
-    /// it with the last element. This does not preserve ordering, but is O(1).
+    /// Removes an element from anywhere in the vector and return it, replacing it with the last
+    /// element.
+    ///
+    /// This does not preserve ordering, but is O(1).
     ///
     /// Returns `None` if `index` is out of bounds.
     ///
@@ -900,13 +929,12 @@ impl<T> Vec<T> {
         self.pop()
     }
 
-    /// Inserts an element at position `index` within the vector, shifting all
-    /// elements after position `i` one position to the right.
+    /// Inserts an element at position `index` within the vector, shifting all elements after
+    /// position `i` one position to the right.
     ///
     /// # Panics
     ///
-    /// Panics if `index` is not between `0` and the vector's length (both
-    /// bounds inclusive).
+    /// Panics if `index` is not between `0` and the vector's length (both bounds inclusive).
     ///
     /// # Examples
     ///
@@ -939,9 +967,9 @@ impl<T> Vec<T> {
         }
     }
 
-    /// Removes and returns the element at position `index` within the vector,
-    /// shifting all elements after position `index` one position to the left.
-    /// Returns `None` if `i` is out of bounds.
+    /// Removes and returns the element at position `index` within the vector, shifting all
+    /// elements after position `index` one position to the left. Returns `None` if `i` is out of
+    /// bounds.
     ///
     /// # Examples
     ///
@@ -980,8 +1008,8 @@ impl<T> Vec<T> {
 
     /// Retains only the elements specified by the predicate.
     ///
-    /// In other words, remove all elements `e` such that `f(&e)` returns false.
-    /// This method operates in place and preserves the order of the retained elements.
+    /// In other words, remove all elements `e` such that `f(&e)` returns false. This method
+    /// operates in place and preserves the order of the retained elements.
     ///
     /// # Examples
     ///
@@ -1070,8 +1098,7 @@ impl<T> Vec<T> {
         }
     }
 
-    /// Removes the last element from a vector and returns it, or `None` if
-    /// it is empty.
+    /// Removes the last element from a vector and returns it, or `None` if it is empty.
     ///
     /// # Examples
     ///
@@ -1099,7 +1126,9 @@ impl<T> Vec<T> {
     ///
     /// ```
     /// let mut v = vec![1i, 2, 3];
+    ///
     /// v.clear();
+    ///
     /// assert!(v.is_empty());
     /// ```
     #[inline]
@@ -1108,7 +1137,7 @@ impl<T> Vec<T> {
         self.truncate(0)
     }
 
-    /// Return the number of elements in the vector
+    /// Returns the number of elements in the vector.
     ///
     /// # Examples
     ///
@@ -1120,13 +1149,14 @@ impl<T> Vec<T> {
     #[stable]
     pub fn len(&self) -> uint { self.len }
 
-    /// Returns true if the vector contains no elements
+    /// Returns `true` if the vector contains no elements.
     ///
     /// # Examples
     ///
     /// ```
     /// let mut v = Vec::new();
     /// assert!(v.is_empty());
+    ///
     /// v.push(1i);
     /// assert!(!v.is_empty());
     /// ```
@@ -1161,7 +1191,9 @@ impl<T: PartialEq> Vec<T> {
     ///
     /// ```
     /// let mut vec = vec![1i, 2, 2, 3, 2];
+    ///
     /// vec.dedup();
+    ///
     /// assert_eq!(vec, vec![1i, 2, 3, 2]);
     /// ```
     #[unstable = "this function may be renamed"]
@@ -1433,10 +1465,9 @@ impl<T> Drop for MoveItems<T> {
 
 /// Converts an iterator of pairs into a pair of vectors.
 ///
-/// Returns a tuple containing two vectors where the i-th element of the first
-/// vector contains the first element of the i-th tuple of the input iterator,
-/// and the i-th element of the second vector contains the second element
-/// of the i-th tuple of the input iterator.
+/// Returns a tuple containing two vectors where the i-th element of the first vector contains the
+/// first element of the i-th tuple of the input iterator, and the i-th element of the second
+/// vector contains the second element of the i-th tuple of the input iterator.
 #[unstable = "this functionality may become more generic over time"]
 pub fn unzip<T, U, V: Iterator<(T, U)>>(mut iter: V) -> (Vec<T>, Vec<U>) {
     let (lo, _) = iter.size_hint();