Rollup merge of #63252 - nrc:arc-doc, r=alexcrichton

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 https://github.com/rust-lang/rust/pull/42137, as a result of https://github.com/rust-lang/rfcs/pull/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 )

1 files changed, 0 insertions, 4 deletions

diff --git a/src/liballoc/sync.rs b/src/liballoc/sync.rs
index 341172136e2..9ffc1673e5a 100644
--- a/src/liballoc/sync.rs
+++ b/src/liballoc/sync.rs
@@ -107,10 +107,6 @@ const MAX_REFCOUNT: usize = (isize::MAX) as usize;
 /// // a, b, and foo are all Arcs that point to the same memory location
 /// ```
 ///
-/// The [`Arc::clone(&from)`] syntax is the most idiomatic because it conveys more explicitly
-/// the meaning of the code. In the example above, this syntax makes it easier to see that
-/// this code is creating a new reference rather than copying the whole content of foo.
-///
 /// ## `Deref` behavior
 ///
 /// `Arc<T>` automatically dereferences to `T` (via the [`Deref`][deref] trait),