Rollup merge of #40505 - frewsxcv:hash-docs, r=alexcrichton

A few improvements to the `core::hash` top-level docs.

Primarily opened to address the concerns brought up in
https://github.com/rust-lang/rust/issues/40498.

* run rustfmt on code blocks
* use `DefaultHasher` instead of deprecated `SipHasher`
* rename `hash` to `calculate_hash` to prevent confusion with the `hash`
  method

diff --combined src/libcore/hash/mod.rs
index aadeaac83d5c85d7d622e8dac1e8e68ab9bdb9e2,8c7d83232de4f0a9379c8e8d2dd002104972c15d..756d472eca8d466ca4ee33190d9713183e85ac4a
--- 1/src/libcore/hash/mod.rs
--- 2/src/libcore/hash/mod.rs
+++ b/src/libcore/hash/mod.rs
@@@ -16,7 -16,8 +16,8 @@@
  //! # Examples
  //!
  //! ```rust
- //! use std::hash::{Hash, SipHasher, Hasher};
+ //! use std::collections::hash_map::DefaultHasher;
+ //! use std::hash::{Hash, Hasher};
  //!
  //! #[derive(Hash)]
  //! struct Person {
@@@ -25,13 -26,21 +26,21 @@@
  //!     phone: u64,
  //! }
  //!
- //! let person1 = Person { id: 5, name: "Janet".to_string(), phone: 555_666_7777 };
- //! let person2 = Person { id: 5, name: "Bob".to_string(), phone: 555_666_7777 };
+ //! let person1 = Person {
+ //!     id: 5,
+ //!     name: "Janet".to_string(),
+ //!     phone: 555_666_7777,
+ //! };
+ //! let person2 = Person {
+ //!     id: 5,
+ //!     name: "Bob".to_string(),
+ //!     phone: 555_666_7777,
+ //! };
  //!
- //! assert!(hash(&person1) != hash(&person2));
+ //! assert!(calculate_hash(&person1) != calculate_hash(&person2));
  //!
- //! fn hash<T: Hash>(t: &T) -> u64 {
- //!     let mut s = SipHasher::new();
+ //! fn calculate_hash<T: Hash>(t: &T) -> u64 {
+ //!     let mut s = DefaultHasher::new();
  //!     t.hash(&mut s);
  //!     s.finish()
  //! }
@@@ -43,11 -52,12 +52,12 @@@
  //! [`Hash`]: trait.Hash.html
  //!
  //! ```rust
- //! use std::hash::{Hash, Hasher, SipHasher};
+ //! use std::collections::hash_map::DefaultHasher;
+ //! use std::hash::{Hash, Hasher};
  //!
  //! struct Person {
  //!     id: u32,
- //! # #[allow(dead_code)]
+ //!     # #[allow(dead_code)]
  //!     name: String,
  //!     phone: u64,
  //! }
@@@ -59,13 -69,21 +69,21 @@@
  //!     }
  //! }
  //!
- //! let person1 = Person { id: 5, name: "Janet".to_string(), phone: 555_666_7777 };
- //! let person2 = Person { id: 5, name: "Bob".to_string(), phone: 555_666_7777 };
+ //! let person1 = Person {
+ //!     id: 5,
+ //!     name: "Janet".to_string(),
+ //!     phone: 555_666_7777,
+ //! };
+ //! let person2 = Person {
+ //!     id: 5,
+ //!     name: "Bob".to_string(),
+ //!     phone: 555_666_7777,
+ //! };
  //!
- //! assert_eq!(hash(&person1), hash(&person2));
+ //! assert_eq!(calculate_hash(&person1), calculate_hash(&person2));
  //!
- //! fn hash<T: Hash>(t: &T) -> u64 {
- //!     let mut s = SipHasher::new();
+ //! fn calculate_hash<T: Hash>(t: &T) -> u64 {
+ //!     let mut s = DefaultHasher::new();
  //!     t.hash(&mut s);
  //!     s.finish()
  //! }
@@@ -106,7 -124,7 +124,7 @@@ mod sip
  ///
  /// This trait can be used with `#[derive]` if all fields implement `Hash`.
  /// When `derive`d, the resulting hash will be the combination of the values
 -/// from calling [`.hash()`] on each field.
 +/// from calling [`.hash`] on each field.
  ///
  /// ## How can I implement `Hash`?
  ///
@@@ -133,7 -151,7 +151,7 @@@
  /// [`Eq`]: ../../std/cmp/trait.Eq.html
  /// [`HashMap`]: ../../std/collections/struct.HashMap.html
  /// [`HashSet`]: ../../std/collections/struct.HashSet.html
 -/// [`.hash()`]: #tymethod.hash
 +/// [`.hash`]: #tymethod.hash
  #[stable(feature = "rust1", since = "1.0.0")]
  pub trait Hash {
      /// Feeds this value into the state given, updating the hasher as necessary.