Improve documentation of safety constraints on hashable objects

[gabbard]

Although #503 referred to cache_hash, on reflection it occurred to me that the concern is valid for all hashable objects. At the same time, I've clarified the documentation to be clear that if you mutate a cache_hash object or an object referred to in its hash computation, the resulting object hash code is undefined. This seemed better than making any more particular comment since it leaves the API uncommitted as to whether the hash code is computed at object-construction time or lazily on the first call to hash

This closes #503 .

Pull Request Check List

This is just a reminder about the most common mistakes. Please make sure that you tick all appropriate boxes. But please read our contribution guide at least once, it will save you unnecessary review cycles!

If an item doesn't apply to your pull request, check it anyway to make it apparent that there's nothing to do.

• Added tests for changed code. (n/a, docs only)
• [X ] New features have been added to our Hypothesis testing strategy. (n/a, docs only)
• Changes or additions to public APIs are reflected in our type stubs (files ending in .pyi). (n/a, docs only)
  • ...and used in the stub test file tests/typing_example.py. (n/a, docs only)
• Updated documentation for changed code.
  • New functions/classes have to be added to docs/api.rst by hand.
  • Changes to the signature of @attr.s() have to be added by hand too.
  • [X ] Changed/added classes/methods/functions have appropriate versionadded, versionchanged, or deprecated directives.
• Documentation in .rst files is written using semantic newlines.
• Changes (and possible deprecations) have news fragments in changelog.d.

If you have any questions to any of the points above, just submit and ask! This checklist is here to help you, not to deter you from contributing!

[gabbard]

@hynek : Ready for review.

[hynek]

thanks!