Update to Rc and Arc documentation to favor the Rc::clone(&ptr) syntax. #42137
Conversation
|
Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @BurntSushi (or someone else) soon. If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes. Please see the contribution instructions for more information. |
|
I am still in process of building the docs locally to check the results (taking ages on this slow computer), there are certainly some adjustments to make and I am not particularly attached to the wording itself. I think that the most important is to bring exposure to the existence of the function call syntax and use it by default in the examples. Perhaps a more detailed explanation of the rationale behind favoring it over the method call syntax should be added to the book rather than the API docs. cc @aturon who was the core team's "ambassador" on that RFC. |
BurntSushi
added
the
T-libs-api
src/liballoc/arc.rs
Outdated
| /// # Cloning references | ||
| /// | ||
| /// Creating a new reference from an existing reference counted pointer is done using the | ||
| /// ```Clone``` trait implemented for [`Arc<T>`][`arc`] and [`Weak<T>`][`weak`]. |
There was a problem hiding this comment.
Inline code blocks can just use one backtick, in this case:
`Clone`
It was decided in the RFC discussion rust-lang/rfcs#1954 to make the function call syntax Rc::clone(&foo) the idiomatic way to clone a reference counted pointer (over the method call syntax foo.clone(). This change updates the documentation of Rc, Arc and their respoective Weak pointers to reflect it and bring more exposure to the existence of the function call syntax.
carols10cents
added
the
S-waiting-on-review
|
ping @BurntSushi, mind taking a look at this PR? |
|
📌 Commit dec23d4 has been approved by |
BurntSushi
removed
the
S-waiting-on-review
shepmaster
added
the
S-waiting-on-bors
Update to Rc and Arc documentation to favor the Rc::clone(&ptr) syntax. This is a followup of the discussion in rust-lang/rfcs#1954. The solution chosen by the core team to address the problem tackled by the [the RFC](rust-lang/rfcs#1954) was to make the function call syntax Rc::clone(&foo) the idiomatic way to clone a reference counted pointer (over the method call syntax foo.clone()). This change updates the documentation of Rc, Arc and their respective Weak pointers to reflect this decision and bring more exposure to the existence of the function call syntax.
Update to Rc and Arc documentation to favor the Rc::clone(&ptr) syntax. This is a followup of the discussion in rust-lang/rfcs#1954. The solution chosen by the core team to address the problem tackled by the [the RFC](rust-lang/rfcs#1954) was to make the function call syntax Rc::clone(&foo) the idiomatic way to clone a reference counted pointer (over the method call syntax foo.clone()). This change updates the documentation of Rc, Arc and their respective Weak pointers to reflect this decision and bring more exposure to the existence of the function call syntax.
Update to Rc and Arc documentation to favor the Rc::clone(&ptr) syntax. This is a followup of the discussion in rust-lang/rfcs#1954. The solution chosen by the core team to address the problem tackled by the [the RFC](rust-lang/rfcs#1954) was to make the function call syntax Rc::clone(&foo) the idiomatic way to clone a reference counted pointer (over the method call syntax foo.clone()). This change updates the documentation of Rc, Arc and their respective Weak pointers to reflect this decision and bring more exposure to the existence of the function call syntax.
|
☀️ Test successful - status-appveyor, status-travis |
|
Huh, I did not know about this idiom change. @carols10cents we might have to update the new book |
|
I was poking around in some Servo code recently and saw that they favor this idiom and i like it :) Will file an issue over there if you haven't already |
Remove recommendation about idiomatic syntax for Arc::clone I believe we should not make this recommendation. I don't want to argue that `Arc::clone` is less idiomatic than `arc.clone`, but that the choice is not clear cut and that we should not be making this kind of call in the docs. The `.clone()` form has advantages too: it is more succinct, it is more likely to be understood by beginners, and it is more uniform with other `clone` calls, indeed with most other method calls. Whichever approach is better, I think that this discussion belongs in a style guide or textbook, rather than the library docs. We don't talk much about idiomatic code in the docs, this place is pretty exceptional. The recommendation is also not followed in this repo. It is hard to figure out how many calls there are of the `.clone()` form, but there are 1550 uses of `Arc` and only 65 uses of `Arc::clone`. The recommendation has existed for over two years. The recommendation was added in rust-lang#42137, as a result of rust-lang/rfcs#1954. However, note that that RFC was closed because it was not necessary to change the docs (the original RFC proposed a new function instead). So I don't think an RFC is necessary here (and I'm not trying to re-litigate the discussion on that RFC (which favoured `Arc::clone` as idiomatic) in any case). cc @nical (who added the docs in the first place; sorry :-) ) r? @alexcrichton (or someone else on @rust-lang/libs )
This is a followup of the discussion in rust-lang/rfcs#1954.
The solution chosen by the core team to address the problem tackled by the the RFC was to make the function call syntax Rc::clone(&foo) the idiomatic way to clone a reference counted pointer (over the method call syntax foo.clone()).
This change updates the documentation of Rc, Arc and their respective Weak pointers to reflect this decision and bring more exposure to the existence of the function call syntax.