From 371e8cf273fed9026e243f59a85eea4d493d132e Mon Sep 17 00:00:00 2001
From: Jason Thompson <jason@jthompson.ca>
Date: Thu, 31 Jul 2014 06:13:44 -0400
Subject: [PATCH] API docs/examples for std::slice

 - API doc/example for next() in Permutations
 - API doc/example for permutations() in ImmutableCloneableVector
 - Moved examples for permutations and next into trait definition as
   comments on pull request #16244.
 - Fix erroneus inclusion of src/llvm in older commit.
---
 src/libcollections/slice.rs | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/src/libcollections/slice.rs b/src/libcollections/slice.rs
index 5b1722b2769..62ac2b2f352 100644
--- a/src/libcollections/slice.rs
+++ b/src/libcollections/slice.rs
@@ -314,6 +314,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>;
 }
 
@@ -334,6 +356,7 @@ fn partitioned(&self, f: |&T| -> bool) -> (Vec<T>, Vec<T>) {
         (lefts, rights)
     }
 
+    /// Returns an iterator over all permutations of a vector.
     fn permutations(self) -> Permutations<T> {
         Permutations{
             swaps: ElementSwaps::new(self.len()),
@@ -580,6 +603,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;
 }