update promotion docs

Author: RalfJung

promotion.md

@@ -1,8 +1,8 @@
 # Const promotion
 
-"Promotion" is the act of guaranteeing that code *not* written in an (explicit)
-const context will be run at compile-time. Explicit const contexts include the
-initializer of a `const` or `static`, or an array length expression.
+"Promotion" is the act of splicing a part of a MIR computation out into a
+separate self-contained MIR body which is evaluated at compile-time like a
+constant.
 
 ## Promotion contexts
 
@@ -44,41 +44,41 @@ attribute, introduced in
 specify these parameters and (aggressively, see below) try to promote the
 corresponding arguments.
 
-### Implicit and explicit contexts
+## Implicit and explicit promotion
 
 On top of what applies to [consts](const.md), promoteds suffer from the additional issue that *the user did not ask for them to be evaluated at compile-time*.
 Thus, if CTFE fails but the code would have worked fine at run-time, we broke the user's code for no good reason.
 Even if we are sure we found an error in the user's code, we are only allowed to [emit a warning, not a hard error][warn-rfc].
-That's why we have to be very conservative with what can and cannot be promoted.
+We call this *implicit* promotion, and we have to be very conservative with what can and cannot be implicitly promoted.
 
-For example, users might be surprised to learn that whenever they take a
-reference to a temporary, that temporary may be promoted away and never
-actually put on the stack. In this way, lifetime extension is an "implicit
-promotion context": the user did not ask for the value to be promoted.
+CTFE of implicitly promoted code must never fail to evaluate except if the
+run-time code also would have failed. This means we cannot permit calling
+arbitrary `const fn`, as discussed in detail in
+[rust-lang/const-eval#19](https://github.com/rust-lang/const-eval/issues/19).
+Thus, only functions marked `#[rustc_promotable]` are implicitly promotable (see
+below).
 
 On the other hand, when a user passes an expression to a function with
-`#[rustc_args_required_const]`, the only way for this code to compile is to promote it.
-In that sense, the user is explicitly asking for that expression
-to be evaluated at compile-time even though they have not written it in a
-`const` declaration. We call this an "explicit promotion context".
+`#[rustc_args_required_const]`, the only way for this code to compile is to
+promote it.  In that sense, the user is explicitly asking for that expression to
+be evaluated at compile-time even though they have not written it in a `const`
+declaration. We can thus be less conservative. This is called *explicit*
+promotion.
 
-Currently, non-`Copy` array initialization is treated as an implicit context,
-because the code could compile even without promotion (namely, if the result
-type is `Copy`).
+Currently, the following are considered explicit promotion contexts:
+* `#[rustc_args_required_const]` arguments
+* the bodies of `const` and `static` items and array lengths
 
-CTFE of implicitly promoted code must never fail to evaluate except of the
-run-time code also would have failed. This means we cannot permit calling
-arbitrary `const fn`, as we cannot predict if they are going to perform an
-["unconst" operation](const_safety.md). Thus, only functions marked
-`#[rustc_promotable]` are implicitly promotable (see below). See
-[rust-lang/const-eval#19](https://github.com/rust-lang/const-eval/issues/19) for
-a thorough discussion of this. At present, this is the only difference between
-implicit and explicit contexts. The requirements for promotion in an implicit
-context are a superset of the ones in an explicit context.
+Everything else is an implicit promotion context, including `const fn` bodies and non-`Copy` array initializers.
+
+In an explicit promotion context, we promote every closed expression (i.e.,
+expressions that do not depend on other variables) of reference type, subject to
+the usual restrictions of [consts](const.md). This means that interior
+mutability and values that need dropping are not promoted.
 
 [warn-rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1229-compile-time-asserts.md
 
-### Promotion contexts inside `const` and `static`
+## Promotion inside `const` and `static`
 
 Lifetime extension is also responsible for making code like this work:
 
@@ -89,14 +89,11 @@ const FOO: &'static i32 = {
 };
 ```
 
-We defined above that promotion guarantees that code in a non-const context
-will be executed at compile-time. The above example illustrates that lifetime
-extension and non-`Copy` array initialization are useful features *inside*
-`const`s and `static`s as well. Strictly speaking, the transformation used to
-enable these features inside a const-context is not promotion; no `promoted`s
-are created in the MIR.  However the same rules for promotability are used with
-one modification: Because the user has already requested that this code run at
-compile time, all contexts are treated as explicit.
+Like in run-time code, a part of the MIR (the one computing `13`) is spliced
+into a separate MIR body, and evaluated like a separate constant.  In the case
+of `const` and `static` initializers, this does not affect how the code is
+evaluated (everything happens at compile-time), but it still affects the
+lifetimes.
 
 Notice that some code involving `&` *looks* like it relies on lifetime
 extension but actually does not:
@@ -105,7 +102,7 @@ extension but actually does not:
 const EMPTY_BYTES: &Vec<u8> = &Vec::new(); // Ok without lifetime extension
 ```
 
-As we have seen above, `Vec::new()` does not get promoted. And yet this
+`Vec::new()` cannot get promoted because it needs dropping. And yet this
 compiles. Why that? The reason is that the reference obtains the lifetime of
 the "enclosing scope", similar to how `let x = &mut x;` creates a reference
 whose lifetime lasts for the enclosing scope. This is decided during MIR