Draft fleshed-out deref docs

library/core/src/ops/deref.rs

@@ -3,15 +3,44 @@
 /// In addition to being used for explicit dereferencing operations with the
 /// (unary) `*` operator in immutable contexts, `Deref` is also used implicitly
 /// by the compiler in many circumstances. This mechanism is called
-/// ['`Deref` coercion'][more]. In mutable contexts, [`DerefMut`] is used.
-///
-/// Implementing `Deref` for smart pointers makes accessing the data behind them
-/// convenient, which is why they implement `Deref`. On the other hand, the
-/// rules regarding `Deref` and [`DerefMut`] were designed specifically to
-/// accommodate smart pointers. Because of this, **`Deref` should only be
-/// implemented for smart pointers** to avoid confusion.
-///
-/// For similar reasons, **this trait should never fail**. Failure during
+/// ['`Deref` coercion'][more]. In mutable contexts, [`DerefMut`] is used and
+/// mutable deref coercion similarly occurs.
+///
+/// Deref coercion is a powerful language feature and has far-reaching
+/// implications for every type implementing `Deref`: the compiler will often
+/// implicitly call `Deref::deref`, as described [below][more]. For this reason,
+/// `Deref` should not be implemented unless all of the implications of coercion
+/// are understood and desired. Implementing `Deref` is most commonly desirable
+/// when a type
+///
+/// 1. should transparently behave like a contained value; and
+/// 2. does not have a rich set of methods in of itself, to avoid conflict or
+///    confusion with methods on the `Target` type.
+///
+/// For example, [`Box<T>`][box] is perhaps the canonical example for `Deref`:
+/// a `Box<T>` value **is** a `T` value that is heap-allocated, so deref
+/// coercion intuitively makes `Box<T>` act like `T`. `Box<T>`
+/// also has very few methods (though several associated functions), so it is
+/// unlikely that users will find conflict with methods on their target type.
+/// [`RefCell<T>`][refcell] also contains a value of `T`, but while it could
+/// implement `DerefMut`, it does not since there is a rich API of methods to
+/// explicitly manage the owned value: allowing deref coercion in this case
+/// would hide the explicit management and likely cause confusion.
+///
+/// Types that implement `Deref` and `DerefMut` are often called "smart
+/// pointers" and the mechanism of deref coercion has been specifically designed
+/// to facilitate the pointer-like behaviour that name suggests. Very often, the
+/// only purpose of a "smart pointer" type is to change the ownership semantics
+/// of a contained value (for example, [`Rc`][rc] or [`Cow`][cow]) or the
+/// storage semantics of a contained value (for example, [`Box`][box]).
+///
+/// If deref coercion is not desirable, the [`AsRef`] or [`Borrow`][borrow]
+/// traits are alternatives which should be preferred in most cases.
+///
+/// # Fallibility
+///
+/// **This trait's method should never fail**. Deref coercion means the compiler
+/// will often implicitly call `Deref::deref`. Failure during
 /// dereferencing can be extremely confusing when `Deref` is invoked implicitly.
 ///
 /// # More on `Deref` coercion
@@ -21,7 +50,8 @@
 /// * In immutable contexts, `*x` (where `T` is neither a reference nor a raw pointer)
 ///   is equivalent to `*Deref::deref(&x)`.
 /// * Values of type `&T` are coerced to values of type `&U`
-/// * `T` implicitly implements all the (immutable) methods of the type `U`.
+/// * `T` implicitly implements all the methods of the type `U` which take the
+///   `&self` receiver.
 ///
 /// For more details, visit [the chapter in *The Rust Programming Language*][book]
 /// as well as the reference sections on [the dereference operator][ref-deref-op],
@@ -32,6 +62,11 @@
 /// [ref-deref-op]: ../../reference/expressions/operator-expr.html#the-dereference-operator
 /// [method resolution]: ../../reference/expressions/method-call-expr.html
 /// [type coercions]: ../../reference/type-coercions.html
+/// [box]: ../../std/boxed/struct.Box.html
+/// [refcell]: ../../std/cell/struct.RefCell.html
+/// [rc]: ../../std/rc/struct.Rc.html
+/// [cow]: ../../std/borrow/enum.Cow.html
+/// [borrow]: ../../std/borrow/trait.Borrow.html
 ///
 /// # Examples
 ///