Improve the generic_arg_infer docs

Syntactically, the inferred const is either an expression or an
`InferredType`, depending on the context.  Semantically, though, it's
a new kind of const generic argument.  Let's add the necessary
language in various places to make this all as clear as possible.

Author: traviscross

src/expressions/array-expr.md

@@ -35,7 +35,18 @@ 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].
+The length operand must either be an [inferred const] or be a [constant expression] of type `usize` (e.g. a [literal] or a [constant item]).
+
+```rust
+const C: usize = 1;
+let _: [u8; C] = [0; 1]; // Literal.
+let _: [u8; C] = [0; C]; // Constant item.
+let _: [u8; C] = [0; _]; // Inferred const.
+let _: [u8; C] = [0; (((_)))]; // Inferred const.
+```
+
+> [!NOTE]
+> In an array expression, an [inferred const] is parsed as an [expression][Expression] but then semantically treated as a separate kind of [const generic argument].
 
 r[expr.array.repeat-behavior]
 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.
@@ -111,8 +122,10 @@ The array index expression can be implemented for types other than arrays and sl
 [IndexMut]: std::ops::IndexMut
 [Index]: std::ops::Index
 [array]: ../types/array.md
+[const generic argument]: items.generics.const.argument
 [constant expression]: ../const_eval.md#constant-expressions
 [constant item]: ../items/constant-items.md
+[inferred const]: items.generics.const.inferred
 [literal]: ../tokens.md#literals
 [memory location]: ../expressions.md#place-expressions-and-value-expressions
 [panic]: ../panic.md

src/items/generics.md

@@ -146,43 +146,56 @@ r[items.generics.const.argument]
 A const argument in a [path] specifies the const value to use for that item.
 
 r[items.generics.const.argument.const-expr]
-The argument must be a [const expression] of the type ascribed to the const
-parameter. The const expression must be a [block expression][block]
-(surrounded with braces) unless it is a single path segment (an [IDENTIFIER])
-or a [literal] (with a possibly leading `-` token).
+The argument must either be an [inferred const] or be a [const expression] of the type ascribed to the const parameter. The const expression must be a [block expression][block] (surrounded with braces) unless it is a single path segment (an [IDENTIFIER]) or a [literal] (with a possibly leading `-` token).
 
 > [!NOTE]
 > This syntactic restriction is necessary to avoid requiring infinite lookahead when parsing an expression inside of a type.
 
 ```rust
-fn double<const N: i32>() {
-    println!("doubled: {}", N * 2);
-}
-
-const SOME_CONST: i32 = 12;
-
-fn example() {
-    // Example usage of a const argument.
-    double::<9>();
-    double::<-123>();
-    double::<{7 + 8}>();
-    double::<SOME_CONST>();
-    double::<{ SOME_CONST + 5 }>();
-}
+struct S<const N: i64>;
+const C: i64 = 1;
+fn f<const N: i64>() -> S<N> { S }
+
+let _ = f::<1>(); // Literal.
+let _ = f::<-1>(); // Negative literal.
+let _ = f::<{ 1 + 2 }>(); // Constant expression.
+let _ = f::<C>(); // Single segment path.
+let _ = f::<{ C + 1 }>(); // Constant expression.
+let _: S<1> = f::<_>(); // Inferred const.
+let _: S<1> = f::<(((_)))>(); // Inferred const.
 ```
 
+> [!NOTE]
+> In a generic argument list, an [inferred const] is parsed as an [inferred type][InferredType] but then semantically treated as a separate kind of [const generic argument].
+
 r[items.generics.const.inferred]
-Where a const argument is expected, an `_` (optionally surrounding by any number of matching parentheses), called the "inferred const", can be used instead. This asks the compiler to infer the const argument if possible based on surrounding information.
+Where a const argument is expected, an `_` (optionally surrounding by any number of matching parentheses), called the *inferred const* ([path rules][paths.expr.complex-const-params], [array expression rules][expr.array.length-restriction]), can be used instead. This asks the compiler to infer the const argument if possible based on surrounding information.
 
 ```rust
-fn make_buf() -> [u8; 1024] {
-    [0x1; _]
-    //    ^ Infers `1024`.
+fn make_buf<const N: usize>() -> [u8; N] {
+    [0; _]
+    //  ^ Infers `N`.
 }
+let _: [u8; 1024] = make_buf::<_>();
+//                             ^ Infers `1024`.
 ```
 
+> [!NOTE]
+> An [inferred const] is not semantically an [expression][Expression] and so is not accepted within braces.
+>
+> ```rust,compile_fail
+> fn f<const N: usize>() -> [u8; N] { [0; _] }
+> let _: [_; 1] = f::<{ _ }>();
+> //                    ^ ERROR `_` not allowed here
+> ```
+
 r[items.generics.const.inferred.constraint]
-It cannot be used in item signatures.
+The inferred const cannot be used in item signatures.
+
+```rust,compile_fail
+fn f<const N: usize>(x: [u8; N]) -> [u8; _] { x }
+//                                       ^ ERROR not allowed
+```
 
 r[items.generics.const.type-ambiguity]
 When there is ambiguity if a generic argument could be resolved as either a
@@ -306,6 +319,7 @@ struct Foo<#[my_flexible_clone(unbounded)] H> {
 [block]: ../expressions/block-expr.md
 [const contexts]: ../const_eval.md#const-context
 [const expression]: ../const_eval.md#constant-expressions
+[const generic argument]: items.generics.const.argument
 [const item]: constant-items.md
 [enumerations]: enumerations.md
 [functions]: functions.md
@@ -314,6 +328,7 @@ struct Foo<#[my_flexible_clone(unbounded)] H> {
 [generic parameter scopes]: ../names/scopes.md#generic-parameter-scopes
 [higher-ranked lifetimes]: ../trait-bounds.md#higher-ranked-trait-bounds
 [implementations]: implementations.md
+[inferred const]: items.generics.const.inferred
 [item declarations]: ../statements.md#item-declarations
 [item]: ../items.md
 [literal]: ../expressions/literal-expr.md

src/paths.md

@@ -91,8 +91,24 @@ The order of generic arguments is restricted to lifetime arguments, then type
 arguments, then const arguments, then equality constraints.
 
 r[paths.expr.complex-const-params]
-Const arguments must be surrounded by braces unless they are a
-[literal] or a single segment path.
+Const arguments must be surrounded by braces unless they are a [literal], an [inferred const], or a single segment path.
+
+```rust
+mod m {
+    pub const C: usize = 1;
+}
+const C: usize = m::C;
+fn f<const N: usize>() -> [u8; N] { [0; N] }
+
+let _ = f::<1>(); // Literal.
+let _: [_; 1] = f::<_>(); // Inferred const.
+let _: [_; 1] = f::<(((_)))>(); // Inferred const.
+let _ = f::<C>(); // Single segment path.
+let _ = f::<{ m::C }>(); // Multi-segment path must be braced.
+```
+
+> [!NOTE]
+> In a generic argument list, an [inferred const] is parsed as an [inferred type][InferredType] but then semantically treated as a separate kind of [const generic argument].
 
 r[paths.expr.impl-trait-params]
 The synthetic type parameters corresponding to `impl Trait` types are implicit,
@@ -480,10 +496,12 @@ mod without { // crate::without
 [`Self` scope]: names/scopes.md#self-scope
 [`use`]: items/use-declarations.md
 [attributes]: attributes.md
+[const generic argument]: items.generics.const.argument
 [enumeration]: items/enumerations.md
 [expressions]: expressions.md
 [extern prelude]: names/preludes.md#extern-prelude
 [implementation]: items/implementations.md
+[inferred const]: items.generics.const.inferred
 [macro transcribers]: macros-by-example.md
 [macros]: macros.md
 [mbe]: macros-by-example.md