Revise text on built-in macro lifetime extension

Rather than discussing the built-in macros directly in the context of
extending expressions, and inspired by our section on implicit
borrows, let's instead add a concept of "macro borrow expressions".
We'll then treat extending macro borrow expressions as extending
expressions and extend the temporary scope of operands to extending
macro borrow expression.

This seems a bit cleaner and better represents the notion that these
macros are only special in that they are a kind of borrow expression.

Author: traviscross

src/destructors.md

@@ -398,11 +398,7 @@ println!("{:?}", C);
 ```
 
 r[destructors.scope.lifetime-extension.sub-expressions]
-If a [borrow][borrow expression], [dereference][dereference expression],
-[field][field expression], or [tuple indexing expression] has an extended
-temporary scope then so does its operand. If an [indexing expression] has an
-extended temporary scope then the indexed expression also has an extended
-temporary scope.
+If a [borrow], [dereference][dereference expression], [field][field expression], or [tuple indexing expression] has an extended temporary scope then so does its operand. If an [indexing expression] has an extended temporary scope then the indexed expression also has an extended temporary scope.
 
 r[destructors.scope.lifetime-extension.patterns]
 #### Extending based on patterns
@@ -479,26 +475,20 @@ For a let statement with an initializer, an *extending expression* is an
 expression which is one of the following:
 
 * The initializer expression.
-* The operand of an extending [borrow expression].
+* The operand of an extending [borrow] or [macro borrow] expression.
 * The operand(s) of an extending [array][array expression], [cast][cast
   expression], [braced struct][struct expression], or [tuple][tuple expression]
   expression.
 * The arguments to an extending [tuple struct] or [tuple variant] constructor expression.
 * The final expression of an extending [block expression] except for an [async block expression].
 * The final expression of an extending [`if`] expression's consequent, `else if`, or `else` block.
 * An arm expression of an extending [`match`] expression.
-* The argument(s) to an extending [`pin!`] or [`format_args!`] [macro invocation] expression.
 
 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.borrow]
-The operand of any extending borrow expression has its temporary scope
-extended.
-
-r[destructors.scope.lifetime-extension.exprs.macros]
-The built-in macros [`pin!`] and [`format_args!`] create temporaries.
-Any extending [`pin!`] or [`format_args!`] [macro invocation] expression has an extended temporary scope.
+r[destructors.scope.lifetime-extension.exprs.borrows]
+The operand of any extending [borrow] or [macro borrow] expression has its temporary scope extended.
 
 > [!NOTE]
 > `rustc` does not treat [array repeat operands] of extending [array] expressions as extending expressions. Whether it should is an open question.
@@ -510,10 +500,10 @@ Any extending [`pin!`] or [`format_args!`] [macro invocation] expression has an
 Here are some examples where expressions have extended temporary scopes:
 
 ```rust,edition2024
+# use core::pin::pin;
 # use core::sync::atomic::{AtomicU64, Ordering::Relaxed};
-# use std::pin::pin;
 # static X: AtomicU64 = AtomicU64::new(0);
-# struct S;
+# #[derive(Debug)] struct S;
 # impl Drop for S { fn drop(&mut self) { X.fetch_add(1, Relaxed); } }
 # const fn temp() -> S { S }
 let x = &temp(); // Operand of borrow.
@@ -536,7 +526,10 @@ let x = if true { &temp() } else { &temp() };
 # x;
 let x = match () { _ => &temp() }; // `match` arm expression.
 # x;
-let x = pin!(&temp()); // Argument to `pin!`.
+let x = pin!(temp()); // Operand of macro borrow expression.
+# x;
+# // TODO: This needs <https://github.com/rust-lang/rust/pull/145882>.
+let x = format_args!("{:?}", temp()); // As above.
 # x;
 //
 // All of the temporaries above are still live here.
@@ -628,7 +621,7 @@ There is one additional case to be aware of: when a panic reaches a [non-unwindi
 [initialized]: glossary.md#initialized
 [interior mutability]: interior-mutability.md
 [lazy boolean expression]: expressions/operator-expr.md#lazy-boolean-operators
-[macro invocation]: macros.md#macro-invocation
+[macro borrow]: expr.macro-borrows
 [non-unwinding ABI boundary]: items/functions.md#unwinding
 [panic]: panic.md
 [place context]: expressions.md#place-expressions-and-value-expressions
@@ -658,7 +651,7 @@ There is one additional case to be aware of: when a panic reaches a [non-unwindi
 [array repeat operands]: expr.array.repeat-operand
 [async block expression]: expr.block.async
 [block expression]: expressions/block-expr.md
-[borrow expression]: expressions/operator-expr.md#borrow-operators
+[borrow]: expr.operator.borrow
 [cast expression]: expressions/operator-expr.md#type-cast-expressions
 [dereference expression]: expressions/operator-expr.md#the-dereference-operator
 [field expression]: expressions/field-expr.md
@@ -675,6 +668,3 @@ There is one additional case to be aware of: when a panic reaches a [non-unwindi
 [`match`]: expressions/match-expr.md
 [`while let`]: expressions/loop-expr.md#while-let-patterns
 [`while`]: expressions/loop-expr.md#predicate-loops
-
-[`pin!`]: std::pin::pin
-[`format_args!`]: core::format_args

src/expressions.md

@@ -175,6 +175,7 @@ The following contexts are *place expression* contexts:
 * The operand of a field expression.
 * The indexed operand of an array indexing expression.
 * The operand of any [implicit borrow].
+* The operand of any [macro borrow expression].
 * The initializer of a [let statement].
 * The [scrutinee] of an [`if let`], [`match`][match], or [`while let`]
   expression.
@@ -286,6 +287,24 @@ Implicit borrows may be taken in the following expressions:
 * Operands of [comparison].
 * Left operands of the [compound assignment].
 
+r[expr.macro-borrows]
+### Macro borrow expressions
+
+r[expr.macro-borrows.intro]
+Calls to certain built-in macros act as [borrow expressions] with respect to some or all of the arguments. These [macro invocations] are *macro borrow expressions*. The arguments borrowed are the *operands* of these macro borrow expressions. As with other borrow expressions, these operands are [place expression contexts] and their [temporary scopes] are [extended][destructors.scope.lifetime-extension.exprs].
+
+r[expr.macro-borrows.exprs]
+The following are macro borrow expressions:
+
+- Calls to [`addr_of!`], [`addr_of_mut!`], or [`pin!`].
+- Calls to [`format_args!`] with at least one argument following the format string.
+
+r[expr.macro-borrows.operands]
+The following are operands of macro borrow expressions:
+
+- The argument to [`addr_of!`], [`addr_of_mut!`], or [`pin!`].
+- Any arguments following the format string to [`format_args!`].
+
 r[expr.overload]
 ## Overloading Traits
 
@@ -310,14 +329,19 @@ They are never allowed before:
 
 [`Copy`]:               special-types-and-traits.md#copy
 [`Drop`]:               special-types-and-traits.md#drop
+[`addr_of!`]:           core::ptr::addr_of
+[`addr_of_mut!`]:       core::ptr::addr_of_mut
 [`if let`]:             expressions/if-expr.md#if-let-patterns
+[`format_args!`]:       core::format_args
+[`pin!`]:               core::pin::pin
 [`Sized`]:              special-types-and-traits.md#sized
 [`while let`]:          expressions/loop-expr.md#while-let-patterns
 [array expressions]:    expressions/array-expr.md
 [array indexing]:       expressions/array-expr.md#array-and-slice-indexing-expressions
 [assign]:               expressions/operator-expr.md#assignment-expressions
 [block expressions]:    expressions/block-expr.md
 [borrow]:               expressions/operator-expr.md#borrow-operators
+[borrow expressions]:   expr.operator.borrow
 [call expressions]:     expressions/call-expr.md
 [comparison]:           expressions/operator-expr.md#comparison-operators
 [compound assignment]:  expressions/operator-expr.md#compound-assignment-expressions
@@ -327,14 +351,18 @@ They are never allowed before:
 [field]:                expressions/field-expr.md
 [functional update]:    expressions/struct-expr.md#functional-update-syntax
 [implicit borrow]:      #implicit-borrows
+[implicitly borrow]:    expr.implicit-borrows
 [implicitly mutably borrowed]: #implicit-borrows
 [interior mutability]:  interior-mutability.md
 [let statement]:        statements.md#let-statements
+[macro borrow expression]: expr.macro-borrows
+[macro invocations]:    macro.invocation
 [match]:                expressions/match-expr.md
 [method-call]:          expressions/method-call-expr.md
 [Mutable `static` items]: items/static-items.md#mutable-statics
 [Outer attributes]:     attributes.md
 [paths]:                expressions/path-expr.md
+[place expression contexts]: expr.place-value
 [promoted]:             destructors.md#constant-promotion
 [Range]:                expressions/range-expr.md
 [raw borrow]:           expressions/operator-expr.md#raw-borrow-operators
@@ -344,6 +372,7 @@ They are never allowed before:
 [static variables]:     items/static-items.md
 [struct]:               expressions/struct-expr.md
 [Structs]:              expr.struct
+[temporary scopes]:     destructors.scope.temporary
 [Temporary values]:     #temporaries
 [tuple expressions]:    expressions/tuple-expr.md
 [Tuple structs]:        items.struct.tuple