Add identifier syntax to array-expr through block-expr

Author: chorman0773

src/expressions/array-expr.md

@@ -1,7 +1,10 @@
 # Array and array index expressions
 
+r[expr.array]
+
 ## Array expressions
 
+r[expr.array.syntax]
 > **<sup>Syntax</sup>**\
 > _ArrayExpression_ :\
 > &nbsp;&nbsp; `[` _ArrayElements_<sup>?</sup> `]`
@@ -10,23 +13,45 @@
 > &nbsp;&nbsp; &nbsp;&nbsp; [_Expression_] ( `,` [_Expression_] )<sup>\*</sup> `,`<sup>?</sup>\
 > &nbsp;&nbsp; | [_Expression_] `;` [_Expression_]
 
+r[expr.array.constructor]
 *Array expressions* construct [arrays][array].
 Array expressions come in two forms.
 
+r[expr.array.array]
 The first form lists out every value in the array.
+
+r[expr.array.array-syntax]
 The syntax for this form is a comma-separated list of expressions of uniform type enclosed in square brackets.
+
+r[expr.array.array-behaviour]
 This produces an array containing each of these values in the order they are written.
 
+r[expr.array.repeat]
 The syntax for the second form is two expressions separated by a semicolon (`;`) enclosed in square brackets.
+
+r[expr.array.repeat-operand]
 The expression before the `;` is called the *repeat operand*.
+
+r[expr.array.length-operand]
 The expression after the `;` is called the *length operand*.
+
+r[expr.array.length-restriction]
 It must have type `usize` and be a [constant expression], such as a [literal] or a [constant item].
+
+r[expr.array.repeat-behaviour]
 An array expression of this form creates an array with the length of the value of the length operand with each element being a copy of the repeat operand.
 That is, `[a; b]` creates an array containing `b` copies of the value of `a`.
+
+r[expr.array.repeat-copy]
 If the length operand has a value greater than 1 then this requires that the type of the repeat operand is [`Copy`] or that it must be a [path] to a constant item.
 
+r[expr.array.repeat-const-item]
 When the repeat operand is a constant item, it is evaluated the length operand's value times.
+
+r[expr.array.repeat-evaluation-zero]
 If that value is `0`, then the constant item is not evaluated at all.
+
+r[expr.array.repeat-non-const]
 For expressions that are not a constant item, it is evaluated exactly once, and then the result is copied the length operand's value times.
 
 ```rust
@@ -41,17 +66,24 @@ const EMPTY: Vec<i32> = Vec::new();
 
 ## Array and slice indexing expressions
 
+r[expr.array.index]
+
 > **<sup>Syntax</sup>**\
 > _IndexExpression_ :\
 > &nbsp;&nbsp; [_Expression_] `[` [_Expression_] `]`
 
+r[expr.array.index.array]
 [Array] and [slice]-typed values can be indexed by writing a square-bracket-enclosed expression of type `usize` (the index) after them.
 When the array is mutable, the resulting [memory location] can be assigned to.
 
+r[expr.array.index.trait]
 For other types an index expression `a[b]` is equivalent to `*std::ops::Index::index(&a, b)`, or `*std::ops::IndexMut::index_mut(&mut a, b)` in a mutable place expression context.
 Just as with methods, Rust will also insert dereference operations on `a` repeatedly to find an implementation.
 
+r[expr.array.index.zero-index]
 Indices are zero-based for arrays and slices.
+
+r[expr.array.index.const]
 Array access is a [constant expression], so bounds can be checked at compile-time with a constant index value.
 Otherwise a check will be performed at run-time that will put the thread in a _panicked state_ if it fails.
 
@@ -73,6 +105,7 @@ let arr = ["a", "b"];
 arr[10];                  // warning: index out of bounds
 ```
 
+r[expr.array.index.trait-impl]
 The array index expression can be implemented for types other than arrays and slices by implementing the [Index] and [IndexMut] traits.
 
 [`Copy`]: ../special-types-and-traits.md#copy

src/expressions/await-expr.md

@@ -1,15 +1,24 @@
 # Await expressions
 
+r[expr.await]
+
+r[expr.await.syntax]
 > **<sup>Syntax</sup>**\
 > _AwaitExpression_ :\
 > &nbsp;&nbsp; [_Expression_] `.` `await`
 
+r[expr.await.intro]
 An `await` expression is a syntactic construct for suspending a computation
 provided by an implementation of `std::future::IntoFuture` until the given
 future is ready to produce a value.
+
+r[expr.await.construct]
 The syntax for an await expression is an expression with a type that implements the [`IntoFuture`] trait, called the *future operand*, then the token `.`, and then the `await` keyword.
+
+r[expr.await.constraints]
 Await expressions are legal only within an [async context], like an [`async fn`], [`async` closure], or [`async` block].
 
+r[expr.await.effects]
 More specifically, an await expression has the following effect.
 
 1. Create a future by calling [`IntoFuture::into_future`] on the future operand.
@@ -23,11 +32,15 @@ More specifically, an await expression has the following effect.
 
 ## Task context
 
+r[expr.await.task]
+
 The task context refers to the [`Context`] which was supplied to the current [async context] when the async context itself was polled.
 Because `await` expressions are only legal in an async context, there must be some task context available.
 
 ## Approximate desugaring
 
+r[expr.await.desugar]
+
 Effectively, an await expression is roughly equivalent to the following non-normative desugaring:
 
 <!-- ignore: example expansion -->

src/expressions/block-expr.md

@@ -1,5 +1,8 @@
 # Block expressions
 
+r[expr.block]
+
+r[expr.block.syntax]
 > **<sup>Syntax</sup>**\
 > _BlockExpression_ :\
 > &nbsp;&nbsp; `{`\
@@ -12,23 +15,35 @@
 > &nbsp;&nbsp; | [_Statement_]<sup>\+</sup> [_ExpressionWithoutBlock_]\
 > &nbsp;&nbsp; | [_ExpressionWithoutBlock_]
 
+r[expr.block.intro]
 A *block expression*, or *block*, is a control flow expression and anonymous namespace scope for items and variable declarations.
+
+r[expr.block.sequential-evaluation]
 As a control flow expression, a block sequentially executes its component non-item declaration statements and then its final optional expression.
+
+r[expr.block.namepsace]
 As an anonymous namespace scope, item declarations are only in scope inside the block itself and variables declared by `let` statements are in scope from the next statement until the end of the block.
 See the [scopes] chapter for more details.
 
+r[expr.block.inner-attributes]
 The syntax for a block is `{`, then any [inner attributes], then any number of [statements], then an optional expression, called the final operand, and finally a `}`.
 
+r[expr.block.statements]
 Statements are usually required to be followed by a semicolon, with two exceptions:
 
 1. Item declaration statements do not need to be followed by a semicolon.
 2. Expression statements usually require a following semicolon except if its outer expression is a flow control expression.
 
+r[expr.block.null-statement]
 Furthermore, extra semicolons between statements are allowed, but these semicolons do not affect semantics.
 
+r[expr.block.evaluation]
 When evaluating a block expression, each statement, except for item declaration statements, is executed sequentially.
+
+r[expr.block.result]
 Then the final operand is executed, if given.
 
+r[expr.block.type]
 The type of a block is the type of the final operand, or `()` if the final operand is omitted.
 
 ```rust
@@ -47,6 +62,7 @@ assert_eq!(5, five);
 
 > Note: As a control flow expression, if a block expression is the outer expression of an expression statement, the expected type is `()` unless it is followed immediately by a semicolon.
 
+r[expr.block.value]
 Blocks are always [value expressions] and evaluate the last operand in value expression context.
 
 > **Note**: This can be used to force moving a value if really needed.
@@ -73,16 +89,27 @@ Blocks are always [value expressions] and evaluate the last operand in value exp
 
 ## `async` blocks
 
+r[expr.block.async]
+
+r[expr.block.async.syntax]
 > **<sup>Syntax</sup>**\
 > _AsyncBlockExpression_ :\
 > &nbsp;&nbsp; `async` `move`<sup>?</sup> _BlockExpression_
 
+r[expr.block.async.intro]
 An *async block* is a variant of a block expression which evaluates to a future.
+
+r[expr.block.async.future-result]
 The final expression of the block, if present, determines the result value of the future.
 
+r[expr.block.async.anonymous-type]
 Executing an async block is similar to executing a closure expression:
 its immediate effect is to produce and return an anonymous type.
+
+r[expr.block.async.future]
 Whereas closures return a type that implements one or more of the [`std::ops::Fn`] traits, however, the type returned for an async block implements the [`std::future::Future`] trait.
+
+r[expr.block.async.layout-unspecified]
 The actual data format for this type is unspecified.
 
 > **Note:** The future type that rustc generates is roughly equivalent to an enum with one variant per `await` point, where each variant stores the data needed to resume from its corresponding point.
@@ -91,22 +118,32 @@ The actual data format for this type is unspecified.
 
 ### Capture modes
 
+r[expr.block.async.capture]
+
 Async blocks capture variables from their environment using the same [capture modes] as closures.
 Like closures, when written `async { .. }` the capture mode for each variable will be inferred from the content of the block.
 `async move { .. }` blocks however will move all referenced variables into the resulting future.
 
 ### Async context
 
+r[expr.block.async.context]
+
 Because async blocks construct a future, they define an **async context** which can in turn contain [`await` expressions].
 Async contexts are established by async blocks as well as the bodies of async functions, whose semantics are defined in terms of async blocks.
 
 ### Control-flow operators
 
+r[expr.block.async.function]
+
+r[expr.block.async.function.intro]
 Async blocks act like a function boundary, much like closures.
+
+r[expr.block.async.function.return-try]
 Therefore, the `?` operator and `return` expressions both affect the output of the future, not the enclosing function or other context.
 That is, `return <expr>` from within an async block will return the result of `<expr>` as the output of the future.
 Similarly, if `<expr>?` propagates an error, that error is propagated as the result of the future.
 
+r[expr.block.async.function.control-flow]
 Finally, the `break` and `continue` keywords cannot be used to branch out from an async block.
 Therefore the following is illegal:
 
@@ -120,15 +157,21 @@ loop {
 
 ## `const` blocks
 
+r[expr.block.const]
+
+r[expr.block.const.syntax]
 > **<sup>Syntax</sup>**\
 > _ConstBlockExpression_ :\
 > &nbsp;&nbsp; `const` _BlockExpression_
 
+r[expr.block.const.intro]
 A *const block* is a variant of a block expression whose body evaluates at compile-time instead of at runtime.
 
+r[expr.block.const.context]
 Const blocks allows you to define a constant value without having to define new [constant items], and thus they are also sometimes referred as *inline consts*.
 It also supports type inference so there is no need to specify the type, unlike [constant items].
 
+r[expr.block.const.generic-params]
 Const blocks have the ability to reference generic parameters in scope, unlike [free][free item] constant items.
 They are desugared to constant items with generic parameters in scope (similar to associated constants, but without a trait or type they are associated with).
 For example, this code:
@@ -153,6 +196,8 @@ fn foo<T>() -> usize {
 }
 ```
 
+r[expr.block.const.evaluation]
+
 If the const block expression is executed at runtime, then the constant is guaranteed to be evaluated, even if its return value is ignored:
 
 ```rust
@@ -166,6 +211,8 @@ fn foo<T>() -> usize {
 }
 ```
 
+r[expr.block.const.not-executed]
+
 If the const block expression is not executed at runtime, it may or may not be evaluated:
 ```rust,compile_fail
 if false {
@@ -176,6 +223,8 @@ if false {
 
 ## `unsafe` blocks
 
+r[expr.block.unsafe]
+
 > **<sup>Syntax</sup>**\
 > _UnsafeBlockExpression_ :\
 > &nbsp;&nbsp; `unsafe` _BlockExpression_
@@ -199,10 +248,15 @@ let a = unsafe { an_unsafe_fn() };
 
 ## Labelled block expressions
 
+r[expr.block.label]
+
 Labelled block expressions are documented in the [Loops and other breakable expressions] section.
 
 ## Attributes on block expressions
 
+r[expr.block.attributes]
+
+r[expr.block.attributes.inner-attributes]
 [Inner attributes] are allowed directly after the opening brace of a block expression in the following situations:
 
 * [Function] and [method] bodies.
@@ -213,6 +267,7 @@ Labelled block expressions are documented in the [Loops and other breakable expr
 * A block expression as the tail expression of another block expression.
 <!-- Keep list in sync with expressions.md -->
 
+r[expr.block.attributes.valid]
 The attributes that have meaning on a block expression are [`cfg`] and [the lint check attributes].
 
 For example, this function returns `true` on unix platforms and `false` on other platforms.