Document Rc/Arc method receivers.

Author: ehuss

src/items/associated-items.md

@@ -93,9 +93,34 @@ Associated functions whose first parameter is named `self` are called *methods*
 and may be invoked using the [method call operator], for example, `x.foo()`, as
 well as the usual function call notation.
 
-If the type of the `self` parameter is specified, it is limited to the type
-being implemented (or `Self`), or a reference or mutable reference to the
-type, or a boxed value of the type being implemented (such as `Box<Self>`).
+If the type of the `self` parameter is specified, it is limited to one of the
+following types:
+
+- `Self`
+- `&Self`
+- `&mut Self`
+- [`Box<Self>`]
+- [`Rc<Self>`]
+- [`Arc<Self>`]
+
+The `Self` portion of the type may be replaced with the type being
+implemented.
+
+```rust
+# use std::rc::Rc;
+# use std::sync::Arc;
+struct Example;
+impl Example {
+    fn by_value(self: Self) {}
+    fn by_ref(self: &Self) {}
+    fn by_ref_mut(self: &mut Self) {}
+    fn by_box(self: Box<Self>) {}
+    fn by_rc(self: Rc<Self>) {}
+    fn by_arc(self: Arc<Self>) {}
+    fn explicit_type(self: Arc<Example>) {}
+}
+```
+
 Shorthand syntax can be used without specifying a type, which have the
 following equivalents:
 
@@ -294,6 +319,9 @@ fn main() {
 [_Lifetime_]: trait-bounds.html
 [_Type_]: types.html#type-expressions
 [_WhereClause_]: items/generics.html#where-clauses
+[`Arc<Self>`]: special-types-and-traits.html#arct
+[`Box<Self>`]: special-types-and-traits.html#boxt
+[`Rc<Self>`]: special-types-and-traits.html#rct
 [trait]: items/traits.html
 [traits]: items/traits.html
 [type aliases]: items/type-aliases.html

src/special-types-and-traits.md

@@ -16,6 +16,14 @@ defined types.
 * A trait may be implemented for `Box<T>` in the same crate as `T`, which the
   [orphan rules] prevent for other generic types.
 
+## `Rc<T>`
+
+[Methods] can take [`Rc<Self>`] as a receiver.
+
+## `Arc<T>`
+
+[Methods] can take [`Arc<Self>`] as a receiver.
+
 ## `UnsafeCell<T>`
 
 [`std::cell::UnsafeCell<T>`] is used for [interior mutability]. It ensures that
@@ -123,12 +131,14 @@ compile-time; that is, it's not a [dynamically sized type]. [Type parameters]
 are `Sized` by default. `Sized` is always implemented automatically by the
 compiler, not by [implementation items].
 
+[`Arc<Self>`]: ../std/sync/struct.Arc.html
 [`Box<T>`]: ../std/boxed/struct.Box.html
 [`Clone`]: ../std/clone/trait.Clone.html
 [`Copy`]: ../std/marker/trait.Copy.html
 [`Deref`]: ../std/ops/trait.Deref.html
 [`DerefMut`]: ../std/ops/trait.DerefMut.html
 [`Drop`]: ../std/ops/trait.Drop.html
+[`Rc<Self>`]: ../std/rc/struct.Rc.html
 [`RefUnwindSafe`]: ../std/panic/trait.RefUnwindSafe.html
 [`Send`]: ../std/marker/trait.Send.html
 [`Sized`]: ../std/marker/trait.Sized.html

src/variables.md

@@ -11,13 +11,13 @@ Local variables are immutable unless declared otherwise. For example:
 `let mut x = ...`.
 
 Function parameters are immutable unless declared with `mut`. The `mut` keyword
-applies only to the following parameter. For example: `|mut x, y|` and 
+applies only to the following parameter. For example: `|mut x, y|` and
 `fn f(mut x: Box<i32>, y: Box<i32>)` declare one mutable variable `x` and one
 immutable variable `y`.
 
-Methods that take either `self` or `Box<Self>` can optionally place them in a
-mutable variable by prefixing them with `mut` (similar to regular arguments).
-For example:
+[Methods] that take `self` or one of the supported `Self` types such as
+`Box<Self>` can optionally place them in a mutable variable by prefixing them
+with `mut` (similar to regular arguments). For example:
 
 ```rust
 trait Changer: Sized {
@@ -52,3 +52,5 @@ fn initialization_example() {
     // uninit_after_if; // err: use of possibly uninitialized `uninit_after_if`
 }
 ```
+
+[Methods]: items/associated-items.html#methods