Skip to content

Commit

Permalink
Doc: explain why Box/Rc/Arc methods do not take self
Browse files Browse the repository at this point in the history
This can be confusing for newcomers, especially due to the argument
name "this".
  • Loading branch information
birkenfeld committed Aug 27, 2016
1 parent 1194695 commit a068fc7
Show file tree
Hide file tree
Showing 3 changed files with 16 additions and 0 deletions.
6 changes: 6 additions & 0 deletions src/liballoc/arc.rs
Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions src/liballoc/boxed.rs
Expand Up @@ -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
///
/// ```
Expand Down
6 changes: 6 additions & 0 deletions src/liballoc/rc.rs
Expand Up @@ -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> {
Expand Down

0 comments on commit a068fc7

Please sign in to comment.