std::ops::Drop documentation focuses on scope, ignores other causes of drops

[hanna-kruppe]

There was some confusion in #rust over when values are dropped. It was pointed out that the std::ops::Drop documentation only says drop is called if "a value goes out of scope", which is inaccurate:

• Scopes apply to variables, not values
• Values can be dropped for other reasons than scopes ending. For example, if a variable is re-assigned, the old value is dropped. There are also temporaries.

I don't know how to best phrase it, but focusing only on scopes is evidently a good way to confuse people.

[nagisa]

I feel like scopes are still the best way to model the intuition about drops, but it is important to understand that scopes used for drop generation aren’t exactly the lexical scopes which you have in the source file.

Most notably drop scopes may overlap in various ways in which the lexical scopes cannot. Similarly, each let binding introduces a scope, which is distinct from any lexical scope you have.

(Re-)assignments are best considered as a sugar for drop(::std::mem::replace(&mut x, y) which does not exactly invalidate the scope-based intuition either.

[hanna-kruppe]

What exactly is a "scope", then? An arbitrary execution path in the CFG? I can't see them being anything less, since all the various operations that cause early drops may be conditional or in loops.

And I find it very strange to "desugar" a primitive language construct such as assignment to a combination of various API calls. I understand it's meant for "intuitive" understanding, but even so it sounds strange and possibly counter-productive for people confused about drop placement.

[Aatch]

I adjusted the title to make it more clear this is talking about documentation, rather than the operation of destructors in general.

[steveklabnik]

doc team triage: p-medium

[steveklabnik]

Triage: no changes, though with NLL, referring to it as a scope will become even more confusing, making this a higher priority.