std: clarify Clone trait documentation about duplication semantics #141215
Conversation
rustbot
added
S-waiting-on-review
|
My role (T-compiler) does not involve approving libs api docs, sorry. r? libs-api |
rustbot
added
the
T-libs-api
fee1-dead
removed
the
T-libs
library/core/src/clone.rs
Outdated
| @@ -38,7 +38,25 @@ | |||
|
|
|||
| mod uninit; | |||
|
|
|||
| /// A common trait for the ability to explicitly duplicate an object. | |||
| /// A common trait that allows explicit creation of a "duplicate" value. | |||
There was a problem hiding this comment.
No need for scare quotes. The value is in fact duplicated.
| /// A common trait that allows explicit creation of a "duplicate" value. | |
| /// A common trait that allows explicit creation of a duplicate value. |
library/core/src/clone.rs
Outdated
| /// ## Important Note on "Duplication" | ||
| /// |
There was a problem hiding this comment.
I don't think this heading adds much? At worst, it's a little confusing due to what else gets moved under it.
| /// ## Important Note on "Duplication" | |
| /// |
library/core/src/clone.rs
Outdated
| /// What "duplication" means depends on the type implementing `Clone`: | ||
| /// | ||
| /// - For most types, calling [`clone`] creates a semantically independent copy with its own | ||
| /// unique identity and state. | ||
| /// - For smart pointers (like [`Arc`], [`Rc`]), [`clone`] increases the reference count but points | ||
| /// to the same underlying data. This means modifications to the underlying data through one | ||
| /// clone will be visible through other clones. | ||
| /// - For reference types (`&T`), [`clone`] just creates another reference to the same value. |
There was a problem hiding this comment.
I don't think that the behavior actually varies much. What is duplicated is the value.
However, some types indeed, as values, are instead references to other data. So you get a new reference. It might be more concise to simply state that you always get a new value, it's just not guaranteed that the new value does not contain references to other data that is not duplicated.
There was a problem hiding this comment.
Besides, this part of the text is just repeated on the docs for Clone::clone itself.
library/core/src/clone.rs
Outdated
| /// [`Arc`]: ../../std/sync/struct.Arc.html | ||
| /// [`Rc`]: ../../std/rc/struct.Rc.html |
There was a problem hiding this comment.
After this we start talking about how this differs from Copy, you see, and that probably doesn't fit under the same heading.
|
This is very not an API change so anyone on libs can take it. yoink |
|
@rustbot author |
rustbot
added
S-waiting-on-author
|
Reminder, once the PR becomes ready for a review, use |
This commit improves the Clone trait documentation to address confusion around what "duplication" means for different types, especially for smart pointers like Arc<Mutex<T>>. Signed-off-by: xizheyin <xizheyin@smail.nju.edu.cn>
| /// Calling [`clone`] always produces a new value. | ||
| /// However, for types that are references to other data (such as smart pointers or references), | ||
| /// the new value may still point to the same underlying data, rather than duplicating it. | ||
| /// See [`Clone::clone`] for more details. |
There was a problem hiding this comment.
I don't categorize it here, I'm just reminding the user of the situation.
| /// Returns a duplicate of the value. | ||
| /// | ||
| /// Note that what "duplicate" means varies by type: | ||
| /// - For most types, this creates a deep, independent copy | ||
| /// - For reference types like `&T`, this creates another reference to the same value | ||
| /// - For smart pointers like [`Arc`] or [`Rc`], this increments the reference count | ||
| /// but still points to the same underlying data | ||
| /// | ||
| /// [`Arc`]: ../../std/sync/struct.Arc.html | ||
| /// [`Rc`]: ../../std/rc/struct.Rc.html |
There was a problem hiding this comment.
Do I need to change it here, also similar to Trait Clone?
rustbot
added
S-waiting-on-review
Closes #141138
The change explicitly explains that cloning behavior varies by type and clarifies that smart pointers (
Arc,Rc) share the same underlying data. I've also added an example of cloning to Arc.r? @fee1-dead