improve __hash__ docs

Doc/reference/datamodel.rst

@@ -1365,21 +1365,21 @@ Basic customization
       object: dictionary
       builtin: hash
 
-   Called for the key object for dictionary operations, and by the built-in
+   Called by built-in function :func:`hash` and for operations on members of
-   function :func:`hash`.  Should return an integer usable as a hash value
+   hashed collections including :class:`set`, :class:`frozenset`, and
-   for dictionary operations.  The only required property is that objects which
+   :class:`dict`.  :meth:`__hash__` should return an integer.  The only required
-   compare equal have the same hash value; it is advised to somehow mix together
+   property is that objects which compare equal have the same hash value; it is
-   (e.g., using exclusive or) the hash values for the components of the object that
+   advised to somehow mix together (e.g. using exclusive or) the hash values for
-   also play a part in comparison of objects.
+   the components of the object that also play a part in comparison of objects.
 
    If a class does not define a :meth:`__cmp__` or :meth:`__eq__` method it
    should not define a :meth:`__hash__` operation either; if it defines
    :meth:`__cmp__` or :meth:`__eq__` but not :meth:`__hash__`, its instances
-   will not be usable as dictionary keys.  If a class defines mutable objects
+   will not be usable in hashed collections.  If a class defines mutable objects
    and implements a :meth:`__cmp__` or :meth:`__eq__` method, it should not
-   implement :meth:`__hash__`, since the dictionary implementation requires that
+   implement :meth:`__hash__`, since hashable collection implementations require
-   a key's hash value is immutable (if the object's hash value changes, it will
+   that a object's hash value is immutable (if the object's hash value changes,
-   be in the wrong hash bucket).
+   it will be in the wrong hash bucket).
 
    User-defined classes have :meth:`__cmp__` and :meth:`__hash__` methods
    by default; with them, all objects compare unequal (except with themselves)
@@ -1389,13 +1389,13 @@ Basic customization
    change the meaning of :meth:`__cmp__` or :meth:`__eq__` such that the hash
    value returned is no longer appropriate (e.g. by switching to a value-based
    concept of equality instead of the default identity based equality) can
-   explicitly flag themselves as being unhashable by setting
+   explicitly flag themselves as being unhashable by setting ``__hash__ = None``
-   ``__hash__ = None`` in the class definition. Doing so means that not only
+   in the class definition. Doing so means that not only will instances of the
-   will instances of the class raise an appropriate :exc:`TypeError` when
+   class raise an appropriate :exc:`TypeError` when a program attempts to
-   a program attempts to retrieve their hash value, but they will also be
+   retrieve their hash value, but they will also be correctly identified as
-   correctly identified as unhashable when checking
+   unhashable when checking ``isinstance(obj, collections.Hashable)`` (unlike
-   ``isinstance(obj, collections.Hashable)`` (unlike classes which define
+   classes which define their own :meth:`__hash__` to explicitly raise
-   their own :meth:`__hash__` to explicitly raise :exc:`TypeError`).
+   :exc:`TypeError`).
 
    .. versionchanged:: 2.5
       :meth:`__hash__` may now also return a long integer object; the 32-bit