Rollup merge of #25074 - killercup:patch-10, r=alexcrichton

 Sweeten the two main HashMap/HashSet examples from [here](http://doc.rust-lang.org/std/collections/struct.HashMap.html) and [here](http://doc.rust-lang.org/std/collections/struct.HashSet.html) with some deref and loop sugar.

(I've only tested this using [this playpen][1].)

[1]: https://play.rust-lang.org/?code=fn%20main()%20%7B%0A%20%20%20%20use%20std%3A%3Acollections%3A%3AHashMap%3B%0A%20%20%20%20%0A%20%20%20%20%2F%2F%20type%20inference%20lets%20us%20omit%20an%20explicit%20type%20signature%20(which%0A%20%20%20%20%2F%2F%20would%20be%20%60HashMap%3C%26str%2C%20%26str%3E%60%20in%20this%20example).%0A%20%20%20%20let%20mut%20book_reviews%20%3D%20HashMap%3A%3Anew()%3B%0A%20%20%20%20%0A%20%20%20%20%2F%2F%20review%20some%20books.%0A%20%20%20%20book_reviews.insert(%22Adventures%20of%20Huckleberry%20Finn%22%2C%20%20%20%20%22My%20favorite%20book.%22)%3B%0A%20%20%20%20book_reviews.insert(%22Grimms%27%20Fairy%20Tales%22%2C%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22Masterpiece.%22)%3B%0A%20%20%20%20book_reviews.insert(%22Pride%20and%20Prejudice%22%2C%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22Very%20enjoyable.%22)%3B%0A%20%20%20%20book_reviews.insert(%22The%20Adventures%20of%20Sherlock%20Holmes%22%2C%20%22Eye%20lyked%20it%20alot.%22)%3B%0A%20%20%20%20%0A%20%20%20%20%2F%2F%20check%20for%20a%20specific%20one.%0A%20%20%20%20if%20!book_reviews.contains_key(%26(%22Les%20Mis%C3%A9rables%22))%20%7B%0A%20%20%20%20%20%20%20%20println!(%22We%27ve%20got%20%7B%7D%20reviews%2C%20but%20Les%20Mis%C3%A9rables%20ain%27t%20one.%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20book_reviews.len())%3B%0A%20%20%20%20%7D%0A%20%20%20%20%0A%20%20%20%20%2F%2F%20oops%2C%20this%20review%20has%20a%20lot%20of%20spelling%20mistakes%2C%20let%27s%20delete%20it.%0A%20%20%20%20book_reviews.remove(%26(%22The%20Adventures%20of%20Sherlock%20Holmes%22))%3B%0A%20%20%20%20%0A%20%20%20%20%2F%2F%20look%20up%20the%20values%20associated%20with%20some%20keys.%0A%20%20%20%20let%20to_find%20%3D%20%5B%22Pride%20and%20Prejudice%22%2C%20%22Alice%27s%20Adventure%20in%20Wonderland%22%5D%3B%0A%20%20%20%20for%20book%20in%20to_find.iter()%20%7B%0A%20%20%20%20%20%20%20%20match%20book_reviews.get(book)%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20Some(review)%20%3D%3E%20println!(%22%7B%7D%3A%20%7B%7D%22%2C%20*book%2C%20*review)%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20None%20%3D%3E%20println!(%22%7B%7D%20is%20unreviewed.%22%2C%20*book)%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%20%20%0A%20%20%20%20%2F%2F%20iterate%20over%20everything.%0A%20%20%20%20for%20(book%2C%20review)%20in%20book_reviews.iter()%20%7B%0A%20%20%20%20%20%20%20%20println!(%22%7B%7D%3A%20%5C%22%7B%7D%5C%22%22%2C%20*book%2C%20*review)%3B%0A%20%20%20%20%7D%0A%20%20%20%20%0A%7D

src/libstd/collections/hash/map.rs

@@ -212,8 +212,9 @@ fn test_resize_policy() {
 /// overridden with one of the constructors.
 ///
 /// It is required that the keys implement the `Eq` and `Hash` traits, although
-/// this can frequently be achieved by using `#[derive(Eq, Hash)]`. If you
-/// implement these yourself, it is important that the following property holds:
+/// this can frequently be achieved by using `#[derive(PartialEq, Eq, Hash)]`.
+/// If you implement these yourself, it is important that the following
+/// property holds:
 ///
 /// ```text
 /// k1 == k2 -> hash(k1) == hash(k2)
@@ -250,26 +251,26 @@ fn test_resize_policy() {
 /// book_reviews.insert("The Adventures of Sherlock Holmes", "Eye lyked it alot.");
 ///
 /// // check for a specific one.
-/// if !book_reviews.contains_key(&("Les Misérables")) {
+/// if !book_reviews.contains_key("Les Misérables") {
 ///     println!("We've got {} reviews, but Les Misérables ain't one.",
 ///              book_reviews.len());
 /// }
 ///
 /// // oops, this review has a lot of spelling mistakes, let's delete it.
-/// book_reviews.remove(&("The Adventures of Sherlock Holmes"));
+/// book_reviews.remove("The Adventures of Sherlock Holmes");
 ///
 /// // look up the values associated with some keys.
 /// let to_find = ["Pride and Prejudice", "Alice's Adventure in Wonderland"];
-/// for book in to_find.iter() {
+/// for book in &to_find {
 ///     match book_reviews.get(book) {
-///         Some(review) => println!("{}: {}", *book, *review),
-///         None => println!("{} is unreviewed.", *book)
+///         Some(review) => println!("{}: {}", book, review),
+///         None => println!("{} is unreviewed.", book)
 ///     }
 /// }
 ///
 /// // iterate over everything.
-/// for (book, review) in book_reviews.iter() {
-///     println!("{}: \"{}\"", *book, *review);
+/// for (book, review) in &book_reviews {
+///     println!("{}: \"{}\"", book, review);
 /// }
 /// ```
 ///
@@ -300,7 +301,7 @@ fn test_resize_policy() {
 /// vikings.insert(Viking::new("Harald", "Iceland"), 12);
 ///
 /// // Use derived implementation to print the status of the vikings.
-/// for (viking, health) in vikings.iter() {
+/// for (viking, health) in &vikings {
 ///     println!("{:?} has {} hp", viking, health);
 /// }
 /// ```

src/libstd/collections/hash/set.rs

@@ -31,10 +31,12 @@
 // to get rid of it properly.
 
 /// An implementation of a hash set using the underlying representation of a
-/// HashMap where the value is (). As with the `HashMap` type, a `HashSet`
-/// requires that the elements implement the `Eq` and `Hash` traits. This can
-/// frequently be achieved by using `#[derive(Eq, Hash)]`. If you implement
-/// these yourself, it is important that the following property holds:
+/// HashMap where the value is ().
+///
+/// As with the `HashMap` type, a `HashSet` requires that the elements
+/// implement the `Eq` and `Hash` traits. This can frequently be achieved by
+/// using `#[derive(PartialEq, Eq, Hash)]`. If you implement these yourself,
+/// it is important that the following property holds:
 ///
 /// ```text
 /// k1 == k2 -> hash(k1) == hash(k2)
@@ -64,17 +66,17 @@
 /// books.insert("The Great Gatsby");
 ///
 /// // Check for a specific one.
-/// if !books.contains(&("The Winds of Winter")) {
+/// if !books.contains("The Winds of Winter") {
 ///     println!("We have {} books, but The Winds of Winter ain't one.",
 ///              books.len());
 /// }
 ///
 /// // Remove a book.
-/// books.remove(&"The Odyssey");
+/// books.remove("The Odyssey");
 ///
 /// // Iterate over everything.
-/// for book in books.iter() {
-///     println!("{}", *book);
+/// for book in &books {
+///     println!("{}", book);
 /// }
 /// ```
 ///
@@ -98,7 +100,7 @@
 /// vikings.insert(Viking { name: "Harald", power: 8 });
 ///
 /// // Use derived implementation to print the vikings.
-/// for x in vikings.iter() {
+/// for x in &vikings {
 ///     println!("{:?}", x);
 /// }
 /// ```