Document properties for Eq + Hash

Fixes #23320

diff --git a/src/libcore/hash/mod.rs b/src/libcore/hash/mod.rs
index 2feb2f8b1e36372d8121b54f2167b631c2d04879..2375ae896500586799867ef4cd6ab5d23d76380a 100644 (file)
--- a/src/libcore/hash/mod.rs
+++ b/src/libcore/hash/mod.rs
@@ -73,6 +73,16 @@
 ///
 /// 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.

diff --git a/src/libstd/collections/hash/map.rs b/src/libstd/collections/hash/map.rs
index 91225891338a58a42dc19542377103de57ff457f..30ccb05cdf0ee7bdd3056c0bbcd7c73cde68b00a 100644 (file)
--- a/src/libstd/collections/hash/map.rs
+++ b/src/libstd/collections/hash/map.rs
@@ -214,7 +214,14 @@ 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)]`.
+/// this can frequently be achieved by using `#[derive(Eq, Hash)]`. If you
+/// implement these yourself, it is important that the following property holds:
+///
+/// ```text
+/// k1 == k2 -> hash(k1) == hash(k2)
+/// ```
+///
+/// In other words, if two keys are equal, their hashes must be equal.
 ///
 /// It is a logic error for a key to be modified in such a way that the key's
 /// hash, as determined by the `Hash` trait, or its equality, as determined by

diff --git a/src/libstd/collections/hash/set.rs b/src/libstd/collections/hash/set.rs
index 0933b4f662a9d744fbec130c491ea1d842e3d944..9bb969c4042670d8fb2089b29e1f06efd116b2f9 100644 (file)
--- a/src/libstd/collections/hash/set.rs
+++ b/src/libstd/collections/hash/set.rs
@@ -36,7 +36,16 @@
 
 /// 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.
+/// 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:
+///
+/// ```text
+/// k1 == k2 -> hash(k1) == hash(k2)
+/// ```
+///
+/// In other words, if two keys are equal, their hashes must be equal.
+///
 ///
 /// It is a logic error for an item to be modified in such a way that the
 /// item's hash, as determined by the `Hash` trait, or its equality, as