PartialEq: handle longer transitive chains

Author: RalfJung

library/core/src/cmp.rs

@@ -58,10 +58,18 @@ use self::Ordering::*;
 ///
 /// - **Transitive**: if `A: PartialEq<B>` and `B: PartialEq<C>` and `A:
 ///   PartialEq<C>`, then **`a == b` and `b == c` implies `a == c`**.
+///   This must also work for longer chains, such as when `A: PartialEq<B>`, `B: PartialEq<C>`,
+///   `C: PartialEq<D>`, and `A: PartialEq<D>` all exist.
 ///
 /// Note that the `B: PartialEq<A>` (symmetric) and `A: PartialEq<C>`
 /// (transitive) impls are not forced to exist, but these requirements apply
 /// whenever they do exist.
+/// The requirement for transitive chains has a subtle consequence: if a crate `a` with type `A`
+/// importing types `B1`, `B2` from another crate `b` defines instances of both `A: PartialEq<B1>`
+/// and `B2: PartialEq<A>`, then if `b` adds a `B1: PartialEq<B2>` implementation in the future that
+/// could create new violations of transitivity. Effectively, crate `a` is making `B1` and `B2`
+/// comparable even though `b` does not permit comparing them. Crate `a` should generally refrain
+/// from doing that to avoid the potential for such conflicts.
 ///
 /// ## Derivable
 ///