implement RFC 1521

Adds documentation to Clone, specifying that Copy types should have a trivial Clone impl.

Fixes #33416.

diff --git a/src/libcore/clone.rs b/src/libcore/clone.rs
index ad2a205a82376c7471460168d33043327bc0bda4..e8ea993c6940a33c9caa0ae37c01bf82fa9c0f8d 100644 (file)
--- a/src/libcore/clone.rs
+++ b/src/libcore/clone.rs
@@ -49,6 +49,11 @@
 /// A common trait for cloning an object.
 ///
 /// This trait can be used with `#[derive]`.
+///
+/// Types that are `Copy` should have a trivial implementation of `Clone`. More formally:
+/// if `T: Copy`, `x: T`, and `y: &T`, then `let x = y.clone();` is equivalent to `let x = *y;`.
+/// Manual implementations should be careful to uphold this invariant; however, unsafe code
+/// must not rely on it to ensure memory safety.
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait Clone : Sized {
     /// Returns a copy of the value.