Reorganize, remove hacks, clarify, and add examples

Author: dianne

src/destructors.md

@@ -458,19 +458,24 @@ let &ref x = &*&temp(); // OK
 r[destructors.scope.lifetime-extension.exprs]
 #### Extending based on expressions
 
+r[destructors.scope.lifetime-extension.exprs.borrows]
+The [temporary scope] of the operand of a [borrow] expression is the *extended scope* of the operand expression, defined below.
+
+r[destructors.scope.lifetime-extension.exprs.super-macros]
+The [scope][temporary scope] of each [super temporary] of a [super macro call] expression is the extended scope of the super macro call expression.
+
 r[destructors.scope.lifetime-extension.exprs.extending]
-An *extending expression* is an expression which is one of the following:
+The extended scope of an expression is defined in terms of *extending expressions* and their *extending parents*. An extending expression is an expression which is one of the following:
 
-* The initializer expression of a `let` statement or the body expression of a [static][static item] or [constant item].
-* The operand of a [borrow] expression.
-* The [super operands] of a [super macro call] expression.
+* The operand of a [borrow] expression, the extending parent of which is the borrow expression.
+* The [super operands] of a [super macro call] expression, the extending parent of which is the macro call expression.
 * The operand(s) of an [array][array expression], [cast][cast
   expression], [braced struct][struct expression], or [tuple][tuple expression]
-  expression.
-* The arguments to a [tuple struct] or [tuple enum variant] constructor expression.
-* The final expression of a [block expression] except for an [async block expression].
-* The final expression of an [`if`] expression's consequent, `else if`, or `else` block.
-* An arm expression of a [`match`] expression.
+  expression, the extending parent of which is the array, cast, braced struct, or tuple expression.
+* The arguments to a [tuple struct] or [tuple enum variant] constructor expression, the extending parent of which is the constructor expression.
+* The final expression of a plain [block expression] or [`unsafe` block expression], the extending parent of which is the block expression.
+* The final expression of an [`if`] expression's consequent, `else if`, or `else` block, the extending parent of which is the `if` expression.
+* An arm expression of a [`match`] expression, the extending parent of which is the `match` expression.
 
 > [!NOTE]
 > The desugaring of a [destructuring assignment] makes its assigned value operand (the RHS) an extending expression within a newly-introduced block. For details, see [expr.assign.destructure.tmp-ext].
@@ -483,20 +488,32 @@ An *extending expression* is an expression which is one of the following:
 So the borrow expressions in `{ &mut 0 }`, `(&1, &mut 2)`, and `Some(&mut 3)`
 are all extending expressions. The borrows in `&0 + &1` and `f(&mut 0)` are not.
 
-r[destructors.scope.lifetime-extension.exprs.borrows]
-The [temporary scope] of the operand of a [borrow] expression is *extended through* the scope of the borrow expression.
-
-r[destructors.scope.lifetime-extension.exprs.super-macros]
-The [scopes][temporary scopes] of the [super temporaries] of an extending [super macro call] expression are *extended through* the scope of the super macro call expression.
-
 r[destructors.scope.lifetime-extension.exprs.parent]
-If a temporary scope is extended through the scope of an extending expression, it is extended through that scope's [parent][destructors.scope.nesting].
+The extended scope of an extending expression is the extended scope of its extending parent.
 
 r[destructors.scope.lifetime-extension.exprs.let]
-A temporary scope extended through a `let` statement scope is [extended] to the scope of the block containing the `let` statement.
+The extended scope of the initializer expression of a `let` statement is the scope of the block containing the `let` statement.
+
+> [!EXAMPLE]
+> In this example, the temporary value holding the result of `temp()` is extended to the end of the block in which `x` is declared:
+>
+> ```rust,edition2024
+> # fn temp() {}
+> let x = { &temp() };
+> println!("{x:?}");
+> ```
+>
+> `temp()` is the operand of a borrow expression, so its temporary scope is its extended scope.
+> To determine its extended scope, look outward:
+>
+> * Since borrow expressions' operands are extending, the extended scope of `temp()` is the extended scope of its extending parent, the borrow expression.
+> * `&temp()` is the final expression of a plain block. Since the final expressions of plain blocks are extending, the extended temporary scope of `&temp()` is the extended scope of its extending parent, the block expression.
+> * `{ &temp() }` is the initializer expression of a `let` statement, so its extended scope is the scope of the block containg that `let` statement.
+>
+> If not for temporary lifetime extension, the result of `temp()` would be dropped after evaluating the tail expression of the block `{ &temp() }` ([destructors.scope.temporary.enclosing]).
 
 r[destructors.scope.lifetime-extension.exprs.static]
-A temporary scope extended through a [static][static item] or [constant item] scope or a [const block][const block expression] scope is [extended] to the end of the program.
+The extended scope of the body expression of a [static][static item] or [constant item], and of the final expression of a [const block expression], is the entire program. This prevents destructors from being run.
 
 ```rust
 const C: &Vec<i32> = &Vec::new();
@@ -507,7 +524,29 @@ println!("{:?}", C);
 ```
 
 r[destructors.scope.lifetime-extension.exprs.other]
-A temporary scope extended through the scope of a non-extending expression is [extended] to that expression's [temporary scope].
+The extended scope of any other expression is its [temporary scope].
+
+> [!NOTE]
+> In this case, the expression is not extending, meaning it cannot be a borrow expression or a [super operand][super operands] to a [super macro call] expression, so its temporary scope is given by [destructors.scope.temporary.enclosing].
+
+> [!EXAMPLE]
+> In this example, the temporary value holding the result of `temp()` is extended to the end of the statement:
+>
+> ```rust,edition2024
+> # fn temp() {}
+> # fn use_temp(_: &()) {}
+> use_temp({ &temp() });
+> ```
+>
+> `temp()` is the operand of a borrow expression, so its temporary scope is its extended scope.
+> To determine its extended scope, look outward:
+>
+> * Since borrow expressions' operands are extending, the extended scope of `temp()` is the extended scope of its extending parent, the borrow expression.
+> * `&temp()` is the final expression of a plain block. Since the final expressions of plain blocks are extending, the extended scope of `&temp()` is the extended scope of its extending parent, the block expression.
+> * `{ &temp() }` is the argument of a call expression, which is not extending. Since no other cases apply, its extended scope is its temporary scope.
+> * Per [destructors.scope.temporary.enclosing], the temporary scope of `{ &temp() }`, and thus the extended scope of `temp()`, is the scope of the statement.
+>
+> If not for temporary lifetime extension, the result of `temp()` would be dropped after evaluating the tail expression of the block `{ &temp() }` ([destructors.scope.temporary.enclosing]).
 
 #### Examples
 
@@ -556,19 +595,6 @@ let x = format_args!("{:?}", temp()); // As above.
 # assert_eq!(0, X.load(Relaxed));
 ```
 
-```rust,edition2024
-# fn temp() {}
-# fn use_temp(_: &()) {}
-// The final expression of a block is extending. Since the block below
-// is not itself extending, the temporary is extended to the block
-// expression's temporary scope, ending at the semicolon.
-use_temp({ &temp() });
-// As above, the final expressions of `if`/`else` blocks are
-// extending, which extends the temporaries to the `if` expression's
-// temporary scope.
-use_temp(if true { &temp() } else { &temp() });
-```
-
 Here are some examples where expressions don't have extended temporary scopes:
 
 ```rust,compile_fail,E0716
@@ -684,7 +710,6 @@ There is one additional case to be aware of: when a panic reaches a [non-unwindi
 
 [array expression]: expressions/array-expr.md#array-expressions
 [array repeat operands]: expr.array.repeat-operand
-[async block expression]: expr.block.async
 [block expression]: expressions/block-expr.md
 [borrow]: expr.operator.borrow
 [cast expression]: expressions/operator-expr.md#type-cast-expressions
@@ -696,11 +721,11 @@ There is one additional case to be aware of: when a panic reaches a [non-unwindi
 [struct expression]: expressions/struct-expr.md
 [super macro call]: expr.super-macros
 [super operands]: expr.super-macros
-[super temporaries]: expr.super-macros
+[super temporary]: expr.super-macros
 [temporary scope]: destructors.scope.temporary
-[temporary scopes]: destructors.scope.temporary
 [tuple expression]: expressions/tuple-expr.md#tuple-expressions
 [tuple indexing expression]: expressions/tuple-expr.md#tuple-indexing-expressions
+[`unsafe` block expression]: expr.block.unsafe
 
 [`for`]: expressions/loop-expr.md#iterator-loops
 [`if let`]: expressions/if-expr.md#if-let-patterns

src/items/constant-items.md

@@ -77,7 +77,7 @@ const C: &mut u8 = unsafe { &mut S }; // ERROR not allowed
 > const C: &AtomicU8 = &AtomicU8::new(0); // ERROR
 > ```
 >
-> Here, the `AtomicU8` is a temporary that is lifetime extended to `'static` (see [destructors.scope.lifetime-extension.static]), and references to lifetime-extended temporaries with interior mutability are not allowed in the final value of a constant expression (see [const-eval.const-expr.borrows]).
+> Here, the `AtomicU8` is a temporary that is lifetime extended to `'static` (see [destructors.scope.lifetime-extension.exprs.static]), and references to lifetime-extended temporaries with interior mutability are not allowed in the final value of a constant expression (see [const-eval.const-expr.borrows]).
 
 r[items.const.expr-omission]
 The constant expression may only be omitted in a [trait definition].