Rollup merge of #35418 - birkenfeld:patch-1, r=aturon

Doc: explain why Box/Rc/Arc methods do not take self

This can be confusing for newcomers, especially due to the argument name `this` that is used for Rc and Arc.

1 files changed, 6 insertions, 0 deletions

diff --git a/src/liballoc/arc.rs b/src/liballoc/arc.rs
index 9c9f1e7b9de..b54b71cabd1 100644
--- a/src/liballoc/arc.rs
+++ b/src/liballoc/arc.rs
@@ -71,6 +71,12 @@ const MAX_REFCOUNT: usize = (isize::MAX) as usize;
 /// does not use atomics, making it both thread-unsafe as well as significantly
 /// faster when updating the reference count.
 ///
+/// Note: the inherent methods defined on `Arc<T>` are all associated functions,
+/// which means that you have to call them as e.g.  `Arc::get_mut(&value)`
+/// instead of `value.get_mut()`.  This is so that there are no conflicts with
+/// methods on the inner type `T`, which are what you want to call in the
+/// majority of cases.
+///
 /// # Examples
 ///
 /// In this example, a large vector of data will be shared by several threads. First we