Auto merge of #23831 - Manishearth:rollup, r=Manishearth

- Successful merges: #23811, #23814, #23817, #23821, #23829
- Failed merges: 

1 files changed, 10 insertions, 0 deletions

diff --git a/src/libcore/hash/mod.rs b/src/libcore/hash/mod.rs
index 2feb2f8b1e3..2375ae89650 100644
--- a/src/libcore/hash/mod.rs
+++ b/src/libcore/hash/mod.rs
@@ -73,6 +73,16 @@ mod sip;
 ///
 /// The `H` type parameter is an abstract hash state that is used by the `Hash`
 /// to compute the hash.
+///
+/// If you are also implementing `Eq`, there is an additional property that
+/// is important:
+///
+/// ```text
+/// k1 == k2 -> hash(k1) == hash(k2)
+/// ```
+///
+/// In other words, if two keys are equal, their hashes should also be equal.
+/// `HashMap` and `HashSet` both rely on this behavior.
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait Hash {
     /// Feeds this value into the state given, updating the hasher as necessary.