Clarify documentation of traits with behavioral contracts (PartialOrd etc.)

[RalfJung]

@Qwaz points out that

Rust's Deref documentation says that this trait should never fail. Similarly, documentation of ExactSizeIterator, PartialOrd, and Hash also describe the behavior of implementations with enforcing words such as must and never.

However, all of these are safe traits, so unsafe code must not rely on such properties. If it does, we have a soundness bug.

I don't think Rust has RFC-style standardization of must/should/etc (maybe it should^^), but at least we should clarify these docs here I feel. Also given that safe code can break these promises, I wonder if "must" is appropriate. Maybe a better wording would be something like

implementations should do X (but since safe code can easily violate this property, users of this trait must not rely on implementations being well-behaved)

[Qwaz]

Related closed RFC here: rust-lang/rfcs#956

[Qwaz]

I was unsure at first if it will be possible to implement all necessary unsafe operations soundly without relying on these behavioral contracts, but after studying data structures in libstd, it seems quite possible. They use proxy objects with transactional methods that will keep the invariant of the underlying data type in all situations.

I think these design patterns are worth being noted in Rustonomicon.

[m-ou-se]

From my comment here:

We might want to clarify that 'must' in this documentation doesn't mean you get UB otherwise, and that you may not rely on these guarantees in unsafe code.

The HashSet documentation contains:

The behavior resulting from such a logic error is not specified, but will not result in undefined behavior. This could include panics, incorrect results, aborts, memory leaks, and non-termination.

We could add something like that here too.