From 30033b45bb2fcbc0f267acaf9fab22411422e166 Mon Sep 17 00:00:00 2001
From: gewitternacht <60887951+gewitternacht@users.noreply.github.com>
Date: Tue, 22 Jul 2025 23:16:49 +0200
Subject: [PATCH] document assumptions about `Clone` and `Eq` traits

---
 library/core/src/clone.rs | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/library/core/src/clone.rs b/library/core/src/clone.rs
index a34d1b4a0649..7afdf50ce51d 100644
--- a/library/core/src/clone.rs
+++ b/library/core/src/clone.rs
@@ -139,6 +139,30 @@ mod uninit;
 /// // Note: With the manual implementations the above line will compile.
 /// ```
 ///
+/// ## `Clone` and `PartialEq`/`Eq`
+/// `Clone` is intended for the duplication of objects. Consequently, when implementing
+/// both `Clone` and [`PartialEq`], the following property is expected to hold:
+/// ```text
+/// x == x -> x.clone() == x
+/// ```
+/// In other words, if an object compares equal to itself,
+/// its clone must also compare equal to the original.
+///
+/// For types that also implement [`Eq`] – for which `x == x` always holds –
+/// this implies that `x.clone() == x` must always be true.
+/// Standard library collections such as
+/// [`HashMap`], [`HashSet`], [`BTreeMap`], [`BTreeSet`] and [`BinaryHeap`]
+/// rely on their keys respecting this property for correct behavior.
+///
+/// This property is automatically satisfied when deriving both `Clone` and [`PartialEq`]
+/// using `#[derive(Clone, PartialEq)]` or when additionally deriving [`Eq`] 
+/// using `#[derive(Clone, PartialEq, Eq)]`.
+///
+/// Violating this property is a logic error. The behavior resulting from a logic error is not
+/// specified, but users of the trait must ensure that such logic errors do *not* result in
+/// undefined behavior. This means that `unsafe` code **must not** rely on the correctness of these
+/// methods.
+///
 /// ## Additional implementors
 ///
 /// In addition to the [implementors listed below][impls],