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

This can be confusing for newcomers, especially due to the argument
name "this".

3 files changed, 16 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
diff --git a/src/liballoc/boxed.rs b/src/liballoc/boxed.rs
index c8a78f84f18..70c429cc360 100644
--- a/src/liballoc/boxed.rs
+++ b/src/liballoc/boxed.rs
@@ -271,6 +271,10 @@ impl<T: ?Sized> Box<T> {
     /// proper way to do so is to convert the raw pointer back into a
     /// `Box` with the `Box::from_raw` function.
     ///
+    /// Note: this is an associated function, which means that you have
+    /// to call it as `Box::into_raw(b)` instead of `b.into_raw()`. This
+    /// is so that there is no conflict with a method on the inner type.
+    ///
     /// # Examples
     ///
     /// ```
diff --git a/src/liballoc/rc.rs b/src/liballoc/rc.rs
index 8e43e9eec16..c24c7ca47ad 100644
--- a/src/liballoc/rc.rs
+++ b/src/liballoc/rc.rs
@@ -182,6 +182,12 @@ struct RcBox<T: ?Sized> {
 /// A reference-counted pointer type over an immutable value.
 ///
 /// See the [module level documentation](./index.html) for more details.
+///
+/// Note: the inherent methods defined on `Rc<T>` are all associated functions,
+/// which means that you have to call them as e.g. `Rc::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.
 #[cfg_attr(stage0, unsafe_no_drop_flag)]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct Rc<T: ?Sized> {