std::vec: clarify & examplify more docs.

src/libstd/vec.rs

@@ -2143,26 +2143,69 @@ pub trait MutableVector<'a, T> {
      */
     fn mut_pop_ref(&mut self) -> &'a mut T;
 
-    /**
-     * Swaps two elements in a vector
-     *
-     * # Arguments
-     *
-     * * a - The index of the first element
-     * * b - The index of the second element
-     */
+    /// Swaps two elements in a vector.
+    ///
+    /// Fails if `a` or `b` are out of bounds.
+    ///
+    /// # Arguments
+    ///
+    /// * a - The index of the first element
+    /// * b - The index of the second element
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// let mut v = ["a", "b", "c", "d"];
+    /// v.swap(1, 3);
+    /// assert_eq!(v, ["a", "d", "c", "b"]);
+    /// ```
     fn swap(self, a: uint, b: uint);
 
-    /**
-     * Divides one `&mut` into two. The first will
-     * contain all indices from `0..mid` (excluding the index `mid`
-     * itself) and the second will contain all indices from
-     * `mid..len` (excluding the index `len` itself).
-     */
+
+    /// Divides one `&mut` into two at an index.
+    ///
+    /// The first will contain all indices from `[0, mid)` (excluding
+    /// the index `mid` itself) and the second will contain all
+    /// indices from `[mid, len)` (excluding the index `len` itself).
+    ///
+    /// Fails if `mid > len`.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// let mut v = [1, 2, 3, 4, 5, 6];
+    ///
+    /// // scoped to restrict the lifetime of the borrows
+    /// {
+    ///    let (left, right) = v.mut_split_at(0);
+    ///    assert_eq!(left, &mut []);
+    ///    assert_eq!(right, &mut [1, 2, 3, 4, 5, 6]);
+    /// }
+    ///
+    /// {
+    ///     let (left, right) = v.mut_split_at(2);
+    ///     assert_eq!(left, &mut [1, 2]);
+    ///     assert_eq!(right, &mut [3, 4, 5, 6]);
+    /// }
+    ///
+    /// {
+    ///     let (left, right) = v.mut_split_at(6);
+    ///     assert_eq!(left, &mut [1, 2, 3, 4, 5, 6]);
+    ///     assert_eq!(right, &mut []);
+    /// }
+    /// ```
     fn mut_split_at(self, mid: uint) -> (&'a mut [T],
                                       &'a mut [T]);
 
-    /// Reverse the order of elements in a vector, in place
+    /// Reverse the order of elements in a vector, in place.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// let mut v = [1, 2, 3];
+    /// v.reverse();
+    /// assert_eq!(v, [3, 2, 1]);
+    /// ```
     fn reverse(self);
 
     /// Sort the vector, in place, using `compare` to compare
@@ -2212,7 +2255,27 @@ pub trait MutableVector<'a, T> {
     #[inline]
     fn as_mut_ptr(self) -> *mut T;
 
-    /// Unsafely sets the element in index to the value
+    /// Unsafely sets the element in index to the value.
+    ///
+    /// This performs no bounds checks, and it is undefined behaviour
+    /// if `index` is larger than the length of `self`. However, it
+    /// does run the destructor at `index`. It is equivalent to
+    /// `self[index] = val`.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// let mut v = ~[~"foo", ~"bar", ~"baz"];
+    ///
+    /// unsafe {
+    ///     // `~"baz"` is deallocated.
+    ///     v.unsafe_set(2, ~"qux");
+    ///
+    ///     // Out of bounds: could cause a crash, or overwriting
+    ///     // other data, or something else.
+    ///     // v.unsafe_set(10, ~"oops");
+    /// }
+    /// ```
     unsafe fn unsafe_set(self, index: uint, val: T);
 
     /// Unchecked vector index assignment.  Does not drop the