Rollup merge of #25087 - nham:improve_vec_docs, r=Gankro

This commit does two things: it adds an example for indexing vectors, and it changes the \"Examples\" section to use full sentences.

This change was spurred by someone in the #rust IRC channel asking if there was a `.set()` method for changing the `i`-th value of a vector (they had missed that `Vec` implements `IndexMut`, which is easy to do if you're not aware of that trait).

src/libcollections/vec.rs

@@ -15,13 +15,13 @@
 //!
 //! # Examples
 //!
-//! Explicitly creating a `Vec<T>` with `new()`:
+//! You can explicitly create a `Vec<T>` with `new()`:
 //!
 //! ```
 //! let xs: Vec<i32> = Vec::new();
 //! ```
 //!
-//! Using the `vec!` macro:
+//! ...or by using the `vec!` macro:
 //!
 //! ```
 //! let ys: Vec<i32> = vec![];
@@ -29,7 +29,7 @@
 //! let zs = vec![1i32, 2, 3, 4, 5];
 //! ```
 //!
-//! Push:
+//! You can `push` values onto the end of a vector (which will grow the vector as needed):
 //!
 //! ```
 //! let mut xs = vec![1i32, 2];
@@ -37,13 +37,21 @@
 //! xs.push(3);
 //! ```
 //!
-//! And pop:
+//! Popping values works in much the same way:
 //!
 //! ```
 //! let mut xs = vec![1i32, 2];
 //!
 //! let two = xs.pop();
 //! ```
+//!
+//! Vectors also support indexing (through the `Index` and `IndexMut` traits):
+//!
+//! ```
+//! let mut xs = vec![1i32, 2, 3];
+//! let three = xs[2];
+//! xs[1] = xs[1] + 5;
+//! ```
 
 #![stable(feature = "rust1", since = "1.0.0")]