Rollup merge of #129938 - chancancode:patch-1, r=thomcc

Elaborate on deriving vs implementing `Copy`

I was reading this documentation and this wasn't immediately clear to me.

In my mind, it seemed obvious that a type can only claim to be `Copy` if the bits it is storing can be `Copy`, and in the case of a generic struct that can only be the case if `T: Copy`. So the bound added by the derive seemed necessary at all times, and I thought what the documentation was trying to say is that the custom implementation allows you to add _additional bounds_.

Of course what it was actually trying to point out is that just because you have a generic parameter `T`, it doesn't necessarily mean you are storing the bits of `T`. And if you aren't, it may be the case that your own bits can be copied regardless of whether the bits of `T` can be safely copied.

Thought it may be worth elaborating to make that a bit more clear. Haven't tested/didn't try to figure out how to render this locally. Mainly not sure if the `PhantomData` back link is going to just work or need some extra stuff, but I figured someone else probably could just tell.

1 files changed, 13 insertions, 2 deletions

diff --git a/library/core/src/marker.rs b/library/core/src/marker.rs
index 5654f5aa4b8..d9f197d9510 100644
--- a/library/core/src/marker.rs
+++ b/library/core/src/marker.rs
@@ -288,8 +288,19 @@ marker_impls! {
 /// }
 /// ```
 ///
-/// There is a small difference between the two: the `derive` strategy will also place a `Copy`
-/// bound on type parameters, which isn't always desired.
+/// There is a small difference between the two. The `derive` strategy will also place a `Copy`
+/// bound on type parameters:
+///
+/// ```
+/// #[derive(Clone)]
+/// struct MyStruct<T>(T);
+///
+/// impl<T: Copy> Copy for MyStruct<T> { }
+/// ```
+///
+/// This isn't always desired. For example, shared references (`&T`) can be copied regardless of
+/// whether `T` is `Copy`. Likewise, a generic struct containing markers such as [`PhantomData`]
+/// could potentially be duplicated with a bit-wise copy.
 ///
 /// ## What's the difference between `Copy` and `Clone`?
 ///