Change:
/// as well as the reference sections on [the dereference operator][ref-deref-op], /// [method resolution] and [type coercions]. /// <ins> /// # Fallibility /// /// **This trait's method should never unexpectedly fail**. Deref coercion means /// the compiler will often insert calls to `DerefMut::deref_mut` implicitly. /// Failure during dereferencing can be extremely confusing when `DerefMut` is /// invoked implicitly. In the majority of uses it should be infallible, though /// it may be acceptable to panic if the type is misused through programmer /// error, for example. /// /// However, infallibility is not enforced and therefore not guaranteed. /// As such, `unsafe` code should not rely on infallibility in general for /// soundness. /// </ins> /// [book]: ../../book/ch15-02-deref.html <del> /// [more]: #more-on-deref-coercion </del> <ins> /// [coercion]: #mutable-deref-coercion /// [implementing]: Deref#when-to-implement-deref-or-derefmut </ins> /// [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 <ins> /// [box]: ../../alloc/boxed/struct.Box.html /// [string]: ../../alloc/string/struct.String.html /// [rc]: ../../alloc/rc/struct.Rc.html /// [cow]: ../../alloc/borrow/enum.Cow.html </ins> /// /// # Examples ///

Discussion:
The documentation for  reads, in part: This warning has sparked significant confusion, which seems to stem from there being no consensus of what actually is a "smart pointer". The warning should be either removed or rewritten in terms of well-understood properties. Relevant URLO discussions:
An alternative could be to actually define the term "smart pointer" somewhere. The reference contains a in section 4.1.13 on , but lacks a definition. However, it is at least questionable whether such a definition could reflect whether should or shouldn't be implemented and at the same time match the common understanding of the term (assuming there is one at all).
Hm from a teaching standpoint, I'd definitely agree the docs shouldn't be introducing jargon without first defining it. And in this case I'm uncertain of the benefit of introducing it at all. In Rust, is the term actually used outside of ? It may be better to directly explain what kinds of types should be implemented for and what would help "avoid confusion". That said, the fuzziness around the term "smart pointer" does allow leeway in interpretation, whereas a too strict definition may not properly reflect how is (or should be) used in practice.
Follow up: The Rust book does actually have a . And then the term is used in the next chapter on . Some quotes from the former:
Incidentally, since the inner 's implementation is sufficient.
Perhaps a better way is to describe when should or shouldn't be implemented. Then the term "smart pointer" or could (in the context of Rust) be defined as "anything that implements ", e.g. in the reference. Currently anything that implements could be seen as smart pointer (depending on how you define it). Given the warning in , this would currently be a circular definition: A smart pointer is something that implements , but should only be implemented for smart pointers. If the warning was removed, the Rust community and the Rust reference could provide a clear definition what a smart pointer (or smart reference, see link above) actually is: Something that implements .
Following my previous comment, the warning could be changed to something like: "Warning: Implementing on a data type will make this data type act like a smart pointer." Or: "turn it into a smart pointer." "This isn't always intended, e.g. when wrapping another type for other reasons."

I feel like actually writing out a definition of smart pointer could be helpful here. Something like "Implementing will often cause instances of the implementing type to be silently converted to the target type. Please consider whether this is desirable before implementing , and avoid implementing it if the distinction between the two types is important." This phrasing is awful, but maybe it captures some of what's intended?
While "smart pointer" was never a precise technical term in any language community, I think what the Deref docs are trying to get at by using the phrase is: A user/library-defined type which is generic over a type T, and which conceptually wraps a single T with indirection. So my strawman rewrite of this paragraph: would be something like this: The TRPL chapter on Smart Pointers I think is acceptable, since that intro-level writing contains a lot of similar simplifications and vague concepts that an expert user would eventually discard, but we can definitely tweak the introduction to make it clearer that "smart pointer" is not a precise term. For example, changing "We’ve already encountered a few smart pointers" to "We've already encountered a few types that could be considered smart pointers".
This is definitely an improvement, but it would be nice to elaborate some on "to avoid confusion:" How might this confusion manifest itself if is implemented improperly? There's also the question of whether any non-"pointer-like" types can reasonably implement . Is it reasonable for a newtype that enforces some property but stores its target value inline, for example: In many ways, this behaves like : It's a container for an owned value with some additional properties enforced by construction. Is this a reasonable use of or not, and how can that be made clear in the docs?
I think that's an assumption that isn't necessarily true. There have been different opinions whether a "smart pointer" needs to be generic (see also the aboved linked discussion thread ). Most prominent example is which, according to the Rust book, is a smart pointer to . If we would consider such non-generic types to not be smart pointers, it still makes sense to implement for some of them. There are several other examples such as (pointing/deref-ing to ), for example. This isn't just limited to types from the standard library but might also be applicable to other types. Introduction in : Also note that a is (much) more than a wrapper to .

Perhaps it could help to elaborate on the "confusion", rather than reference smart pointers. For example, it could discuss how any method you add to something which implements is a potential shadowing risk for something on the target. (And thus why -- which doesn't -- has a method , but -- which does -- has an associated function that's not a method.)
We discussed this in our T-libs meeting today and our consensus was that we would welcome a PR that clarifies this, but that we don't feel comfortable making a decisions regarding the discussion so far in the absence of such a PR that introduces concrete wording. We definitely agree with the general direction of clarifying when to use Deref and how it restricts your API design decisions going forward, and that we shouldn't center jargon terminology like "smart pointer".
Also relevant to the discussion: currently the standard library implements for s, including something like , which in the owned case features no pointer/indirection. In general, I find this whole warning to be a bit too opinionated and subjective, since, as we can see, it's difficult to come up with hard rules. I thus second more practical approach of: "beware that implementing and (inherent) methods can be footgunny or surprising; types that implement ought to strive not to feature other methods_".
See also Christopher Durham's attempt to define a smart pointer .
A bit more complete; here's how I currently lean towards defining a "smart pointer:" (From a crate.) Details are of course extremely fungible (and docs are still incomplete), but the main idea is that a "smart pointer" is "raw pointer + smarts," so it should be defined by conversions into/from a raw pointer. [^2]: The name is a pun on tartare being a raw meat dish. and were taken, but the connotation is still something raw which can be made safe with special care. (plz no squat) .
I've taken a crack at drafting something that I think it clearer and gives more helpful guidance: Comments very much welcome and if this direction seems good I will polish for proper review.