`HashMap` docs don't mention `{Eq, Hash}` consistency

[apasel422]

While it may not be possible to enforce this at the type level, the docs for HashMap (and HashSet) should specify that its key type's {Eq, Hash} implementations must be consistent for the map to have reasonable behavior. The exact requirement is

k1 == k2 -> hash(k1) == hash(k2)

This is always the case for derived implementations, but the following example is nonsensical if Foo is used as a HashMap key:

#[derive(Hash)]
struct Foo(u32, u32);

impl PartialEq for Foo {
    fn eq(&self, other: &Foo) -> bool { self.0 == other.0 }
}

impl Eq for Foo {}

There could additionally be some kind of debug-level assertion of this behavior, or possibly a lint that checks to make sure that the fields that are referenced in PartialEq::eq and Hash::hash are consistent. The lint wouldn't be perfect, but could be useful.

This belongs to the class of properties that are great to check for with quickcheck.

use std::fmt::Debug;
use std::hash::{hash, Hash, SipHasher};
use quickcheck::{Arbitrary, quickcheck};

fn prop_sane_hash<T: Arbitrary + Debug + Hash + PartialEq>(a: T, b: T) -> bool {
    a != b || hash::<_, SipHasher>(&a) == hash::<_, SipHasher>(&b)
}
fn main() {
    quickcheck(prop_sane_hash as fn(Foo, Foo) -> bool);
}

[kennytm]

I think this is a generic property that should be mentioned in Hash, not just HashMap/HashSet.