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 "borrow macro call
expressions".  We'll then treat extending borrow macro call
expressions as extending expressions and extend the temporary scope of
operands to extending borrow macro call 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 operator] or [borrow macro] call 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 operator] or [borrow macro] call 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 borrow macro call 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.
@@ -621,14 +614,14 @@ There is one additional case to be aware of: when a panic reaches a [non-unwindi
 
 [Assignment]: expressions/operator-expr.md#assignment-expressions
 [binding modes]: patterns.md#binding-modes
+[borrow macro]: expr.borrow-macros
 [closure]: types/closure.md
 [destructors]: destructors.md
 [expression]: expressions.md
 [identifier pattern]: patterns.md#identifier-patterns
 [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
 [non-unwinding ABI boundary]: items/functions.md#unwinding
 [panic]: panic.md
 [place context]: expressions.md#place-expressions-and-value-expressions
@@ -658,7 +651,8 @@ 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 operator]: expr.operator.borrow
+[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 +669,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.borrow-macros]
+### Borrow macros
+
+r[expr.borrow-macros.intro]
+Calls to certain built-in macros act as [borrow expressions] with respect to some or all of the arguments. These [macro invocations] are *borrow macro call expressions*. The arguments borrowed are the *operands* of these borrow macro call 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.borrow-macros.exprs]
+The following are borrow macro call 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.borrow-macros.operands]
+The following are operands of borrow macro call 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.borrow-macros
+[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