auto merge of #16417 : jasonthompson/rust/docs/slice3, r=alexcrichton

- Moved examples for permutations and next into trait definition as
   comments on pull request #16244.
- Fixed (hopefully) issue with erronious commit of changes to src/llvm.

Author: bors

src/libcollections/slice.rs

@@ -301,6 +301,28 @@ pub trait ImmutableCloneableVector<T> {
 
     /// Create an iterator that yields every possible permutation of the
     /// vector in succession.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// let v = [1i, 2, 3];
+    /// let mut perms = v.permutations();
+    ///
+    /// for p in perms {
+    ///   println!("{}", p);
+    /// }
+    /// ```
+    ///
+    /// # Example 2: iterating through permutations one by one.
+    ///
+    /// ```rust
+    /// let v = [1i, 2, 3];
+    /// let mut perms = v.permutations();
+    ///
+    /// assert_eq!(Some(vec![1i, 2, 3]), perms.next());
+    /// assert_eq!(Some(vec![1i, 3, 2]), perms.next());
+    /// assert_eq!(Some(vec![3i, 1, 2]), perms.next());
+    /// ```
     fn permutations(self) -> Permutations<T>;
 }
 
@@ -321,6 +343,7 @@ impl<'a,T:Clone> ImmutableCloneableVector<T> for &'a [T] {
         (lefts, rights)
     }
 
+    /// Returns an iterator over all permutations of a vector.
     fn permutations(self) -> Permutations<T> {
         Permutations{
             swaps: ElementSwaps::new(self.len()),
@@ -567,6 +590,16 @@ pub trait MutableVectorAllocating<'a, T> {
      * * src - A mutable vector of `T`
      * * start - The index into `src` to start copying from
      * * end - The index into `src` to stop copying from
+     *
+     * # Example
+     *
+     * ```rust
+     * let mut a = [1i, 2, 3, 4, 5];
+     * let b = vec![6i, 7, 8];
+     * let num_moved = a.move_from(b, 0, 3);
+     * assert_eq!(num_moved, 3);
+     * assert!(a == [6i, 7, 8, 4, 5]);
+     * ```
      */
     fn move_from(self, src: Vec<T>, start: uint, end: uint) -> uint;
 }