From 7835c8c06cc80b5a0d3d08c1ab1b91240a8aec52 Mon Sep 17 00:00:00 2001 From: Jan Riemer Date: Sun, 2 Aug 2020 14:57:19 +0200 Subject: [PATCH 1/7] docs(marker/copy): clarify that `&T` is also `Copy` In the current documentation about the `Copy` marker trait, there is a section about "additional implementors", which list additional implementors of the `Copy` trait. The fact that shared references are also `Copy` is mixed with another point, which makes it hard to recognize and make it seem not as important. This clarifies the fact that shared references are also `Copy`, by mentioning it as a separate item in the list of "additional implementors". --- library/core/src/marker.rs | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/library/core/src/marker.rs b/library/core/src/marker.rs index 56dddee7b7799..255f4474ea07d 100644 --- a/library/core/src/marker.rs +++ b/library/core/src/marker.rs @@ -347,9 +347,8 @@ pub trait StructuralEq { /// * Tuple types, if each component also implements `Copy` (e.g., `()`, `(i32, bool)`) /// * Closure types, if they capture no value from the environment /// or if all such captured values implement `Copy` themselves. -/// Note that variables captured by shared reference always implement `Copy` -/// (even if the referent doesn't), -/// while variables captured by mutable reference never implement `Copy`. +/// * Variables captured by shared reference (e.g. `&T`) implement `Copy`, even if the referent (`T`) doesn't, +/// while variables captured by mutable reference (e.g. `&mut T`) never implement `Copy`. /// /// [`Vec`]: ../../std/vec/struct.Vec.html /// [`String`]: ../../std/string/struct.String.html From a876b3d8aaf21510e569ce62dfc6c50a3cf3efd3 Mon Sep 17 00:00:00 2001 From: Jan Riemer Date: Sun, 16 Aug 2020 20:03:34 +0200 Subject: [PATCH 2/7] docs(marker/copy): provide example for `&T` being `Copy` In the current documentation about the `Copy` marker trait, there is a section with examples of structs that can implement `Copy`. Currently there is no example for showing that shared references (`&T`) are also `Copy`. It is worth to have a dedicated example for `&T` being `Copy`, because shared references are an integral part of the language and it being `Copy` is not as intuitive as other types that share this behaviour like `i32` or `bool`. The example picks up on the previous non-`Copy` struct and shows that structs can be `Copy`, even when they hold a shared reference to a non-`Copy` type. --- library/core/src/marker.rs | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/library/core/src/marker.rs b/library/core/src/marker.rs index 255f4474ea07d..1458d25d7f7d2 100644 --- a/library/core/src/marker.rs +++ b/library/core/src/marker.rs @@ -315,6 +315,18 @@ pub trait StructuralEq { /// the trait `Copy` may not be implemented for this type; field `points` does not implement `Copy` /// ``` /// +/// Shared references (`&T`) are also `Copy`, so a struct can be `Copy`, even when it holds +/// shared references of types `T` that are *not* `Copy`. Consider the following struct, +/// which can implement `Copy`, because it only holds a *shared reference* to our non-`Copy` +/// type `PointList` from above: +/// ``` +/// # #![allow(dead_code)] +/// # struct PointList; +/// struct PointListWrapper<'a> { +/// point_list_ref: &'a PointList, +/// } +/// ``` +/// /// ## When *can't* my type be `Copy`? /// /// Some types can't be copied safely. For example, copying `&mut T` would create an aliased @@ -347,8 +359,9 @@ pub trait StructuralEq { /// * Tuple types, if each component also implements `Copy` (e.g., `()`, `(i32, bool)`) /// * Closure types, if they capture no value from the environment /// or if all such captured values implement `Copy` themselves. -/// * Variables captured by shared reference (e.g. `&T`) implement `Copy`, even if the referent (`T`) doesn't, -/// while variables captured by mutable reference (e.g. `&mut T`) never implement `Copy`. +/// Note that variables captured by shared reference always implement `Copy` +/// (even if the referent doesn't), +/// while variables captured by mutable reference never implement `Copy`. /// /// [`Vec`]: ../../std/vec/struct.Vec.html /// [`String`]: ../../std/string/struct.String.html @@ -539,7 +552,7 @@ macro_rules! impls { /// For a more in-depth explanation of how to use `PhantomData`, please see /// [the Nomicon](../../nomicon/phantom-data.html). /// -/// # A ghastly note 👻👻👻 +/// # A ghastly note /// /// Though they both have scary names, `PhantomData` and 'phantom types' are /// related, but not identical. A phantom type parameter is simply a type From 43dec0e1715b5f20a36527f3e0ab3e09594e846d Mon Sep 17 00:00:00 2001 From: Jan Riemer Date: Sun, 16 Aug 2020 20:17:28 +0200 Subject: [PATCH 3/7] rephrase: struct -> type Co-authored-by: Joshua Nelson --- library/core/src/marker.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/core/src/marker.rs b/library/core/src/marker.rs index 1458d25d7f7d2..b698cbd7802de 100644 --- a/library/core/src/marker.rs +++ b/library/core/src/marker.rs @@ -315,7 +315,7 @@ pub trait StructuralEq { /// the trait `Copy` may not be implemented for this type; field `points` does not implement `Copy` /// ``` /// -/// Shared references (`&T`) are also `Copy`, so a struct can be `Copy`, even when it holds +/// Shared references (`&T`) are also `Copy`, so a type can be `Copy`, even when it holds /// shared references of types `T` that are *not* `Copy`. Consider the following struct, /// which can implement `Copy`, because it only holds a *shared reference* to our non-`Copy` /// type `PointList` from above: From dce864454c3748dd4119eac40b0dd35772467fb2 Mon Sep 17 00:00:00 2001 From: Jan Riemer Date: Sun, 16 Aug 2020 20:19:21 +0200 Subject: [PATCH 4/7] add back emojis that have been removed accidentally Co-authored-by: Joshua Nelson --- library/core/src/marker.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/core/src/marker.rs b/library/core/src/marker.rs index b698cbd7802de..a9f8e332d2851 100644 --- a/library/core/src/marker.rs +++ b/library/core/src/marker.rs @@ -552,7 +552,7 @@ macro_rules! impls { /// For a more in-depth explanation of how to use `PhantomData`, please see /// [the Nomicon](../../nomicon/phantom-data.html). /// -/// # A ghastly note +/// # A ghastly note 👻👻👻 /// /// Though they both have scary names, `PhantomData` and 'phantom types' are /// related, but not identical. A phantom type parameter is simply a type From 9061da2e14afee47f039b74ecadae97b737c6c9b Mon Sep 17 00:00:00 2001 From: Jan Riemer Date: Sun, 16 Aug 2020 22:15:59 +0200 Subject: [PATCH 5/7] add empty line above code block Co-authored-by: Poliorcetics --- library/core/src/marker.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/library/core/src/marker.rs b/library/core/src/marker.rs index a9f8e332d2851..85e2e3830a513 100644 --- a/library/core/src/marker.rs +++ b/library/core/src/marker.rs @@ -319,6 +319,7 @@ pub trait StructuralEq { /// shared references of types `T` that are *not* `Copy`. Consider the following struct, /// which can implement `Copy`, because it only holds a *shared reference* to our non-`Copy` /// type `PointList` from above: +/// /// ``` /// # #![allow(dead_code)] /// # struct PointList; From 56daf63d10f7ade09ab0523333c65370a88c79ae Mon Sep 17 00:00:00 2001 From: Jan Riemer Date: Sun, 16 Aug 2020 22:25:59 +0200 Subject: [PATCH 6/7] docs: add `derive` for struct Code blocks in doc comments are compiled and run, so we show `Copy` works in this example. Co-authored-by: Poliorcetics --- library/core/src/marker.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/library/core/src/marker.rs b/library/core/src/marker.rs index 85e2e3830a513..f113f9392301a 100644 --- a/library/core/src/marker.rs +++ b/library/core/src/marker.rs @@ -323,6 +323,7 @@ pub trait StructuralEq { /// ``` /// # #![allow(dead_code)] /// # struct PointList; +/// #[derive(Copy, Clone)] /// struct PointListWrapper<'a> { /// point_list_ref: &'a PointList, /// } From 522d177f34e683b16d3548446aa3ff7ddd2c531c Mon Sep 17 00:00:00 2001 From: Jan Riemer Date: Tue, 18 Aug 2020 18:40:19 +0200 Subject: [PATCH 7/7] docs: add another `derive` for `Copy`able struct This adds another `derive` for a `Copy`able struct, so that we are consistent with `derive` annotations. --- library/core/src/marker.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/library/core/src/marker.rs b/library/core/src/marker.rs index f113f9392301a..9326aaf56847c 100644 --- a/library/core/src/marker.rs +++ b/library/core/src/marker.rs @@ -291,6 +291,7 @@ pub trait StructuralEq { /// /// ``` /// # #[allow(dead_code)] +/// #[derive(Copy, Clone)] /// struct Point { /// x: i32, /// y: i32,