Deref docs: expand and remove "smart pointer" qualifier

[jmaargh]

Ready for review

This is an unpolished draft to be sanity-checked

Fixes #91004

Comments on substance and content of this are welcome. This is deliberately unpolished until ready to review so please try to stay focused on the big-picture.

Once this has been sanity checked, I will similarly update DerefMut and polish for review.

[rustbot]

r? @Mark-Simulacrum

(rustbot has picked a reviewer for you, use r? to override)

[stepancheg]

PathBuf derefs to Path, but it does not fit well into that definition: it has quite rich set of methods. And it does not seem to be a smart pointer.

Similarly, consider scenario: AbsPath wrapper for Path which only type-asserts that path is absolute. It is unclear from this description whether it is OK for AbsPath to deref to Path.

Style suggestion: make a subsection in the rustdoc something like "When to implement Deref and when not" to make clearer distinction between precise behavior or Deref from language point of view, and a guide when to implement.

[jmaargh]

Good suggestion on the sectioning. I think it's still a good idea to keep a "you really should think carefully about this"-style warning near the top, but the details can certainly be secontioned off.

Thinking again, I guess there are two broad "typical" cases. I covered the "generic" case where you're dereffing to some unknown type. For String and PathBuf style cases, you're dereffing to a known type, so they point about a rich API isn't so relevant. I'll have a crack at incorporating this other type tomorrow.

[Noratrieb]

Maybe the method restriction is better expressed as "doesn't have methods that could potentially conflict with the target type". Box is generic over any type, so any method could be conflicting. Vec and slice are carefully set up in a way to make sure that nothing could be conflicting (they have some overlap, but the overlapping methods do the same thing).

[JanBeh]

Regarding "Deref should not fail", I would like to refer to this post/thread on URLO where I stated the hypothesis that it's more about stability rather than failure (and bringing up the case of once_cell::sync::Lazy or the unstable std::sync::LazyLock, see also #74465).

[jmaargh]

I'm happy I left this alone for a bit to gather comments. I'll synthesise these over the next day or two and produce a revised draft which should be ready for non-draft-PR status.

In particular, I'll try and find a good balance that is comprehensive enough for official docs, but does not stray into "this should be a book chapter" territory. I think this will necessarily mean concentrating on good, simple advice that works the large majority of the time while sidelining the many many exceptions where it can be sensible to break the letter of that advice.

[Dylan-DPC]

@jmaargh any updates on this? thanks

[Noratrieb]

note that this repo does not allow these merge commits, you need to rebase: https://rustc-dev-guide.rust-lang.org/git.html#i-made-a-merge-commit-by-accident

[jmaargh]

Apologies for the delay.

I've redrafted with the comments in mind. The idea is to clearly state the potential problems with implementing these traits, and then give general advice which should apply for most users. I've tried to strike the right balance between giving clear advice and accuracy. However, I've purposefully avoided trying to be encyclopaedic since that could easily balloon into a short book chapter.

Particular changes:

• followed the long-stated "definition" of "smart pointers" from the book (I'm not seeking to adjudicate on whether this is the "right" definition, but it's a term in use so mentioning it here seems appropriate)
• broke out "fallibility" sections, since that advice stood out to me as perhaps the most pertinent
• kept the longer advice section to Deref and linked to it from DerefMut (easily duplicated if this isn't desirable style)

As always, happy for comments.

[kpreid]

I think that as currently written, this pair of paragraphs can be interpreted as too strong a claim. Note that Vec<T> is a generic type, but its Deref implementation is, in the terms of this section, a “specific” one because it dereferences to [T] rather than T. The thing to watch out for is not impl<T> Deref for Foo<T>, but type Target = T.

Attempted expansion to clarify this:

Generic implementations, such as for [`Box<T>`][box] (which is generic over
every type and dereferences to `T`) should be careful to provide few or no
methods, since the target type is unknown and therefore every method could
collide with one on the target type, causing confusion for users.
`impl<T> Box<T>` has no methods (though several associated functions),
partly for this reason.

Specific implementations, such as for [`String`][string] (whose `Deref`
implementation has `Target = str`) can have many methods, since avoiding
collision is much easier. `String` and `str` both have many methods, and
`String` additionally behaves as if it has every method of `str` because of
deref coercion. The implementing type may also be generic while the
implementation is still specific in this sense; for example, [`Vec<T>`][vec]
dereferences to `[T]`, so methods of `T` are not applicable.

I also revised the statement that Box<T> has few methods; in fact it has no methods. The only methods on the Box page are for e.g. Box<MaybeUninit<T>>, not Box<T>.

[bors]

☔ The latest upstream changes (presumably #115889) made this pull request unmergeable. Please resolve the merge conflicts.

[Dylan-DPC]

@jmaargh any updates on this?

[jmaargh]

@Dylan-DPC I guess I was waiting on reviews. I'll incorporate @kpreid 's suggestion verbatim now, because I think it works and is not too verbose. Otherwise, IMHO this is ready to merge with enough reviews

[jmaargh]

There was a merge conflict from the change introduced in PR #115607, which added the following (after the previous comment about how this "...must not fail..."):

Violating these requirements is a logic error. The behavior resulting from a logic error is not
specified, but users of the trait must ensure that such logic errors do not result in
undefined behavior. This means that unsafe code must not rely on the correctness of this
method.

Frankly, this took me a while to understand at all (what are "these requirements", exactly? by "users" do we mean implementors of this trait, or some other users? this trait is safe so we can't cause undefined behaviour without unsafe code so... what are we talking about?) I guess this isn't helped by the fact that paragraph was pasted near-verbatim across several structs, rather than written for each context.

Reviewing the original issue that PR was solving ( #73682 ), I decided to replace it with the above, which I think covers the required ground while being more understandable.

[jmaargh]

@rustbot review

[Mark-Simulacrum]

This looks good to me. I think we should squash commits, can you do that? Then we can merge.

[jmaargh]

@Mark-Simulacrum Squashed, should be good to merge after CI

[Mark-Simulacrum]

@bors r+ rollup

[bors]

📌 Commit 7a2f83f has been approved by Mark-Simulacrum

It is now in the queue for this repository.