Improve documentation of safety constraints on hashable objects (#505)

* Clarify documentation for hashing

Makes clear that hashable objects need to be deeply immutable, in
practice even if not in theory.

Closes #503 .

* Use simple past tense in docs

changelog.d/503.change.rst

@@ -0,0 +1 @@
+Clarified documentation for hashing to warn that hashable objects should be deeply immutable (in their usage, even if this is not enforced).

docs/hashing.rst

@@ -66,7 +66,9 @@ For a more thorough explanation of this topic, please refer to this blog post: `
 Hashing and Mutability
 ----------------------
 Changing any field involved in hash code computation after the first call to `__hash__` (typically this would be after its insertion into a hash-based collection) can result in silent bugs.
-Therefore, it is strongly recommended that hashable classes be ``frozen``.
+Therefore, it is strongly recommended that hashable classes be ``frozen.``
+Beware, however, that this is not a complete guarantee of safety:
+if a field points to an object and that object is mutated, the hash code may change, but ``frozen`` will not protect you.
 
 
 Hash Code Caching

src/attr/_make.py

@@ -843,10 +843,10 @@ def attrs(
     :param bool cache_hash: Ensure that the object's hash code is computed
         only once and stored on the object.  If this is set to ``True``,
         hashing must be either explicitly or implicitly enabled for this
-        class.  If the hash code is cached, then no attributes of this
-        class which participate in hash code computation may be mutated
-        after object creation.
-
+        class.  If the hash code is cached, avoid any reassignments of
+        fields involved in hash code computation or mutations of the objects
+        those fields point to after object creation.  If such changes occur,
+        the behavior of the object's hash code is undefined.
 
     .. versionadded:: 16.0.0 *slots*
     .. versionadded:: 16.1.0 *frozen*