std::vec: Update module doc text

Update for a lot of changes (not many free functions left), add examples
of the important methods `slice` and `push`, and write a short bit about
iteration.

Author: blake2-ppc

src/libstd/vec.rs

@@ -10,8 +10,9 @@
 
 /*!
 
-The `vec` module contains useful code to help work with vector values. Vectors are Rust's list
-type. Vectors contain zero or more values of homogeneous types:
+The `vec` module contains useful code to help work with vector values.
+Vectors are Rust's list type. Vectors contain zero or more values of
+homogeneous types:
 
 ~~~ {.rust}
 let int_vector = [1,2,3];
@@ -27,32 +28,72 @@ represents iteration over a vector.
 
 ## Traits
 
-A number of traits that allow you to accomplish tasks with vectors, like the
-`MutableVector` and `ImmutableVector` traits.
+A number of traits add methods that allow you to accomplish tasks with vectors.
+
+Traits defined for the `&[T]` type (a vector slice), have methods that can be
+called on either owned vectors, denoted `~[T]`, or on vector slices themselves.
+These traits include `ImmutableVector`, and `MutableVector` for the `&mut [T]`
+case.
+
+An example is the method `.slice(a, b)` that returns an immutable "view" into
+a vector or a vector slice from the index interval `[a, b)`:
+
+~~~ {.rust}
+let numbers = [0, 1, 2];
+let last_numbers = numbers.slice(1, 3);
+// last_numbers is now &[1, 2]
+~~~
+
+Traits defined for the `~[T]` type, like `OwnedVector`, can only be called
+on such vectors. These methods deal with adding elements or otherwise changing
+the allocation of the vector.
+
+An example is the method `.push(element)` that will add an element at the end
+of the vector:
+
+~~~ {.rust}
+let mut numbers = ~[0, 1, 2];
+numbers.push(7);
+// numbers is now ~[0, 1, 2, 7];
+~~~
 
 ## Implementations of other traits
 
-Vectors are a very useful type, and so there's tons of implementations of
-traits found elsewhere. Some notable examples:
+Vectors are a very useful type, and so there's several implementations of
+traits from other modules. Some notable examples:
 
 * `Clone`
-* `Iterator`
-* `Zero`
+* `Eq`, `Ord`, `TotalEq`, `TotalOrd` -- vectors can be compared,
+  if the element type defines the corresponding trait.
 
-## Function definitions
+## Iteration
+
+The method `iter()` returns an iteration value for a vector or a vector slice.
+The iterator yields borrowed pointers to the vector's elements, so if the element
+type of the vector is `int`, the element type of the iterator is `&int`.
 
-There are a number of different functions that take vectors, here are some
-broad categories:
+~~~ {.rust}
+let numbers = [0, 1, 2];
+for &x in numbers.iter() {
+    println!("{} is a number!", x);
+}
+~~~
+
+* `.rev_iter()` returns an iterator with the same values as `.iter()`,
+  but going in the reverse order, starting with the back element.
+* `.mut_iter()` returns an iterator that allows modifying each value.
+* `.move_iter()` converts an owned vector into an iterator that
+  moves out a value from the vector each iteration.
+* Further iterators exist that split, chunk or permute the vector.
+
+## Function definitions
 
-* Modifying a vector, like `append` and `grow`.
-* Searching in a vector, like `bsearch`.
-* Iterating over vectors, like `each_permutation`.
-* Functional transformations on vectors, like `map` and `partition`.
-* Stack/queue operations, like `push`/`pop` and `shift`/`unshift`.
-* Cons-y operations, like `head` and `tail`.
-* Zipper operations, like `zip` and `unzip`.
+There are a number of free functions that create or take vectors, for example:
 
-And much, much more.
+* Creating a vector, like `from_elem` and `from_fn`
+* Creating a vector with a given size: `with_capacity`
+* Modifying a vector and returning it, like `append`
+* Operations on paired elements, like `unzip`.
 
 */