Cleanup collections::slice documentation.

This does a few things:

 - remove references to ~[] and the OwnedVector trait, which are both
   obsolete
 - correct the docs to say that this is the slice module, not the vec
   module
 - add a sentence pointing out that vectors are distinct from Vec
 - remove documentation on Vec.

closes #15459

src/libcollections/slice.rs

@@ -10,35 +10,46 @@
 
 /*!
 
-Utilities for vector manipulation
+Utilities for slice manipulation
 
-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 `slice` module contains useful code to help work with slice values.
+Slices are a view into a block of memory represented as a pointer and a length.
 
 ```rust
-let int_vector = [1i, 2i, 3i];
-let str_vector = ["one", "two", "three"];
+// slicing a Vec
+let vec = vec!(1i, 2, 3);
+let int_slice = vec.as_slice();
+// coercing an array to a slice
+let str_slice: &[&str] = ["one", "two", "three"];
 ```
 
-This is a big module, but for a high-level overview:
+Slices are either mutable or shared. The shared slice type is `&[T]`,
+while the mutable slice type is `&mut[T]`. For example, you can mutate the
+block of memory that a mutable slice points to:
+
+```rust
+let x: &mut[int] = [1i, 2, 3];
+x[1] = 7;
+assert_eq!(x[0], 1);
+assert_eq!(x[1], 7);
+assert_eq!(x[2], 3);
+```
+
+Here are some of the things this module contains:
 
 ## Structs
 
-Several structs that are useful for vectors, such as `Items`, which
-represents iteration over a vector.
+There are several structs that are useful for slices, such as `Items`, which
+represents iteration over a slice.
 
 ## 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.
+A number of traits add methods that allow you to accomplish tasks with slices.
+These traits include `ImmutableVector`, which is defined for `&[T]` types,
+and `MutableVector`, defined for `&mut [T]` types.
 
 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)`:
+a `Vec` or another slice from the index interval `[a, b)`:
 
 ```rust
 let numbers = [0i, 1i, 2i];
@@ -46,33 +57,20 @@ let last_numbers = numbers.slice(1, 3);
 // last_numbers is now &[1i, 2i]
 ```
 
-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 = vec![0i, 1i, 2i];
-numbers.push(7);
-// numbers is now vec![0i, 1i, 2i, 7i];
-```
-
 ## Implementations of other traits
 
-Vectors are a very useful type, and so there's several implementations of
-traits from other modules. Some notable examples:
+There are several implementations of common traits for slices. Some examples
+include:
 
 * `Clone`
-* `Eq`, `Ord`, `Eq`, `Ord` -- vectors can be compared,
-  if the element type defines the corresponding trait.
+* `Eq`, `Ord` - for immutable slices whose element type are `Eq` or `Ord`.
+* `Hash` - for slices whose element type is `Hash`
 
 ## Iteration
 
-The method `iter()` returns an iteration value for a vector or a vector slice.
-The iterator yields references to the vector's elements, so if the element
-type of the vector is `int`, the element type of the iterator is `&int`.
+The method `iter()` returns an iteration value for a slice. The iterator
+yields references to the slice's elements, so if the element
+type of the slice is `int`, the element type of the iterator is `&int`.
 
 ```rust
 let numbers = [0i, 1i, 2i];
@@ -82,18 +80,7 @@ for &x in numbers.iter() {
 ```
 
 * `.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
-
-There are a number of free functions that create or take vectors, for example:
-
-* 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`.
+* Further iterators exist that split, chunk or permute the slice.
 
 */