Rollup merge of #53782 - rask:task/arc-docs-adjustment, r=cramertj

Make Arc cloning mechanics clearer in module docs

Add some more wording to module documentation regarding how
`Arc::clone()` works, as some users have assumed cloning Arc's
to work via dereferencing to inner value as follows:

    use std::sync::Arc;

    let myarc = Arc::new(1);
    let myarcref = myarc.clone();

    assert!(1 == myarcref);

Instead of the actual mechanic of referencing the existing
Arc value:

    use std::sync::Arg;

    let myarc = Arc::new(1);
    let myarcref = myarc.clone();

    assert!(myarcref == &myarc); // not sure if assert could assert this in the real world

1 files changed, 5 insertions, 4 deletions

diff --git a/src/liballoc/sync.rs b/src/liballoc/sync.rs
index 2cd7898f4c7..db7a4044b26 100644
--- a/src/liballoc/sync.rs
+++ b/src/liballoc/sync.rs
@@ -49,9 +49,10 @@ const MAX_REFCOUNT: usize = (isize::MAX) as usize;
 ///
 /// The type `Arc<T>` provides shared ownership of a value of type `T`,
 /// allocated in the heap. Invoking [`clone`][clone] on `Arc` produces
-/// a new pointer to the same value in the heap. When the last `Arc`
-/// pointer to a given value is destroyed, the pointed-to value is
-/// also destroyed.
+/// a new `Arc` instance, which points to the same value on the heap as the
+/// source `Arc`, while increasing a reference count. When the last `Arc`
+/// pointer to a given value is destroyed, the pointed-to value is also
+/// destroyed.
 ///
 /// Shared references in Rust disallow mutation by default, and `Arc` is no
 /// exception: you cannot generally obtain a mutable reference to something
@@ -107,7 +108,7 @@ const MAX_REFCOUNT: usize = (isize::MAX) as usize;
 /// // The two syntaxes below are equivalent.
 /// let a = foo.clone();
 /// let b = Arc::clone(&foo);
-/// // a and b both point to the same memory location as foo.
+/// // 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