Merge pull request rust-lang#920 from ehuss/fix-generic-params

Update grammar for order of parameters/arguments.
ehuss · Jan 10, 2021 · f8c39fe · f8c39fe
2 parents 448002d + 9d0aa17
commit f8c39fe
Show file tree

Hide file tree

Showing 11 changed files with 41 additions and 63 deletions.
diff --git a/src/items/associated-items.md b/src/items/associated-items.md
@@ -80,7 +80,7 @@ let _: f64 = f64::from_i32(42);
 ### Methods
 
 > _Method_ :\
-> &nbsp;&nbsp; [_FunctionQualifiers_] `fn` [IDENTIFIER]&nbsp;[_Generics_]<sup>?</sup>\
+> &nbsp;&nbsp; [_FunctionQualifiers_] `fn` [IDENTIFIER]&nbsp;[_GenericParams_]<sup>?</sup>\
 > &nbsp;&nbsp; &nbsp;&nbsp; `(` _SelfParam_ (`,` [_FunctionParam_])<sup>\*</sup> `,`<sup>?</sup> `)`\
 > &nbsp;&nbsp; &nbsp;&nbsp; [_FunctionReturnType_]<sup>?</sup> [_WhereClause_]<sup>?</sup>\
 > &nbsp;&nbsp; &nbsp;&nbsp; [_BlockExpression_]
@@ -344,7 +344,7 @@ fn main() {
 [_FunctionParam_]: functions.md
 [_FunctionQualifiers_]: functions.md
 [_FunctionReturnType_]: functions.md
-[_Generics_]: generics.md
+[_GenericParams_]: generics.md
 [_Lifetime_]: ../trait-bounds.md
 [_Type_]: ../types.md#type-expressions
 [_WhereClause_]: generics.md#where-clauses

diff --git a/src/items/enumerations.md b/src/items/enumerations.md
@@ -4,7 +4,7 @@
 > _Enumeration_ :\
 > &nbsp;&nbsp; `enum`
 >    [IDENTIFIER]&nbsp;
->    [_Generics_]<sup>?</sup>
+>    [_GenericParams_]<sup>?</sup>
 >    [_WhereClause_]<sup>?</sup>
 >    `{` _EnumItems_<sup>?</sup> `}`
 >
@@ -172,7 +172,7 @@ enum E {
 ```
 
 [IDENTIFIER]: ../identifiers.md
-[_Generics_]: generics.md
+[_GenericParams_]: generics.md
 [_WhereClause_]: generics.md#where-clauses
 [_Expression_]: ../expressions.md
 [_TupleFields_]: structs.md

diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md
@@ -17,7 +17,7 @@
 > &nbsp;&nbsp; `static` `mut`<sup>?</sup> [IDENTIFIER] `:` [_Type_] `;`
 >
 > _ExternalFunctionItem_ :\
-> &nbsp;&nbsp; `fn` [IDENTIFIER]&nbsp;[_Generics_]<sup>?</sup>\
+> &nbsp;&nbsp; `fn` [IDENTIFIER]&nbsp;[_GenericParams_]<sup>?</sup>\
 > &nbsp;&nbsp; `(` ( _NamedFunctionParameters_ | _NamedFunctionParametersWithVariadics_ )<sup>?</sup> `)`\
 > &nbsp;&nbsp; [_FunctionReturnType_]<sup>?</sup> [_WhereClause_]<sup>?</sup> `;`
 >
@@ -190,7 +190,7 @@ restrictions as [regular function parameters].
 [statics]: static-items.md
 [_Abi_]: functions.md
 [_FunctionReturnType_]: functions.md
-[_Generics_]: generics.md
+[_GenericParams_]: generics.md
 [_InnerAttribute_]: ../attributes.md
 [_MacroInvocationSemi_]: ../macros.md#macro-invocation
 [_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax

diff --git a/src/items/functions.md b/src/items/functions.md
@@ -2,7 +2,7 @@
 
 > **<sup>Syntax</sup>**\
 > _Function_ :\
-> &nbsp;&nbsp; _FunctionQualifiers_ `fn` [IDENTIFIER]&nbsp;[_Generics_]<sup>?</sup>\
+> &nbsp;&nbsp; _FunctionQualifiers_ `fn` [IDENTIFIER]&nbsp;[_GenericParams_]<sup>?</sup>\
 > &nbsp;&nbsp; &nbsp;&nbsp; `(` _FunctionParameters_<sup>?</sup> `)`\
 > &nbsp;&nbsp; &nbsp;&nbsp; _FunctionReturnType_<sup>?</sup> [_WhereClause_]<sup>?</sup>\
 > &nbsp;&nbsp; &nbsp;&nbsp; [_BlockExpression_]
@@ -341,7 +341,7 @@ fn foo_oof(#[some_inert_attribute] arg: u8) {
 [RAW_STRING_LITERAL]: ../tokens.md#raw-string-literals
 [STRING_LITERAL]: ../tokens.md#string-literals
 [_BlockExpression_]: ../expressions/block-expr.md
-[_Generics_]: generics.md
+[_GenericParams_]: generics.md
 [_Pattern_]: ../patterns.md
 [_Type_]: ../types.md#type-expressions
 [_WhereClause_]: generics.md#where-clauses

diff --git a/src/items/generics.md b/src/items/generics.md
@@ -1,31 +1,21 @@
 # Generic parameters
 
 > **<sup>Syntax</sup>**\
-> _Generics_ :\
-> &nbsp;&nbsp; `<` _GenericParams_ `>`
->
 > _GenericParams_ :\
-> &nbsp;&nbsp; &nbsp;&nbsp; _LifetimeParams_\
-> &nbsp;&nbsp; | ( _LifetimeParam_ `,` )<sup>\*</sup> _TypeParams_\
-> &nbsp;&nbsp; | ( _LifetimeParam_ `,` )<sup>\*</sup> ( _TypeParam_ `,` )<sup>\*</sup> _ConstParams_
+> &nbsp;&nbsp; &nbsp;&nbsp; `<` `>`\
+> &nbsp;&nbsp;  | `<` (_GenericParam_ `,`)<sup>\*</sup> _GenericParam_ `,`<sup>?</sup> `>`
 >
-> _LifetimeParams_ :\
-> &nbsp;&nbsp; ( _LifetimeParam_ `,` )<sup>\*</sup> _LifetimeParam_<sup>?</sup>
+> _GenericParam_ :\
+> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> ( _LifetimeParam_ | _TypeParam_ | _ConstParam_ )
 >
 > _LifetimeParam_ :\
-> &nbsp;&nbsp; [_OuterAttribute_]<sup>?</sup> [LIFETIME_OR_LABEL]&nbsp;( `:` [_LifetimeBounds_] )<sup>?</sup>
->
-> _TypeParams_:\
-> &nbsp;&nbsp; ( _TypeParam_ `,` )<sup>\*</sup> _TypeParam_<sup>?</sup>
+> &nbsp;&nbsp; [LIFETIME_OR_LABEL]&nbsp;( `:` [_LifetimeBounds_] )<sup>?</sup>
 >
 > _TypeParam_ :\
-> &nbsp;&nbsp; [_OuterAttribute_]<sup>?</sup> [IDENTIFIER]( `:` [_TypeParamBounds_]<sup>?</sup> )<sup>?</sup> ( `=` [_Type_] )<sup>?</sup>
->
-> _ConstParams_:\
-> &nbsp;&nbsp; ( _ConstParam_ `,` )<sup>\*</sup> _ConstParam_<sup>?</sup>
+> &nbsp;&nbsp; [IDENTIFIER]( `:` [_TypeParamBounds_]<sup>?</sup> )<sup>?</sup> ( `=` [_Type_] )<sup>?</sup>
 >
 > _ConstParam_:\
-> &nbsp;&nbsp; [_OuterAttribute_]<sup>?</sup> `const` [IDENTIFIER] `:` [_Type_]
+> &nbsp;&nbsp; `const` [IDENTIFIER] `:` [_Type_]
 
 Functions, type aliases, structs, enumerations, unions, traits, and
 implementations may be *parameterized* by types, constants, and lifetimes. These
@@ -91,12 +81,15 @@ referred to with path syntax.
 > &nbsp;&nbsp; _ForLifetimes_<sup>?</sup> [_Type_] `:` [_TypeParamBounds_]<sup>?</sup>
 >
 > _ForLifetimes_ :\
-> &nbsp;&nbsp; `for` `<` [_LifetimeParams_](#generic-parameters) `>`
+> &nbsp;&nbsp; `for` [_GenericParams_](#generic-parameters)
 
 *Where clauses* provide another way to specify bounds on type and lifetime
 parameters as well as a way to specify bounds on types that aren't type
 parameters.
 
+The `for` keyword can be used to introduce [higher-ranked lifetimes]. It only
+allows [_LifetimeParam_] parameters.
+
 Bounds that don't use the item's parameters or higher-ranked lifetimes are
 checked when the item is defined. It is an error for such a bound to be false.
 
@@ -141,6 +134,7 @@ struct Foo<#[my_flexible_clone(unbounded)] H> {
 [IDENTIFIER]: ../identifiers.md
 [LIFETIME_OR_LABEL]: ../tokens.md#lifetimes-and-loop-labels
 
+[_LifetimeParam_]: #generic-parameters
 [_LifetimeBounds_]: ../trait-bounds.md
 [_Lifetime_]: ../trait-bounds.md
 [_OuterAttribute_]: ../attributes.md
@@ -150,6 +144,7 @@ struct Foo<#[my_flexible_clone(unbounded)] H> {
 [arrays]: ../types/array.md
 [const contexts]: ../const_eval.md#const-context
 [function pointers]: ../types/function-pointer.md
+[higher-ranked lifetimes]: ../trait-bounds.md#higher-ranked-trait-bounds
 [raw pointers]: ../types/pointer.md#raw-pointers-const-and-mut
 [references]: ../types/pointer.md#shared-references-
 [repeat expressions]: ../expressions/array-expr.md

diff --git a/src/items/implementations.md b/src/items/implementations.md
@@ -5,7 +5,7 @@
 > &nbsp;&nbsp; _InherentImpl_ | _TraitImpl_
 >
 > _InherentImpl_ :\
-> &nbsp;&nbsp; `impl` [_Generics_]<sup>?</sup>&nbsp;[_Type_]&nbsp;[_WhereClause_]<sup>?</sup> `{`\
+> &nbsp;&nbsp; `impl` [_GenericParams_]<sup>?</sup>&nbsp;[_Type_]&nbsp;[_WhereClause_]<sup>?</sup> `{`\
 > &nbsp;&nbsp; &nbsp;&nbsp; [_InnerAttribute_]<sup>\*</sup>\
 > &nbsp;&nbsp; &nbsp;&nbsp; _InherentImplItem_<sup>\*</sup>\
 > &nbsp;&nbsp; `}`
@@ -17,7 +17,7 @@
 > &nbsp;&nbsp; )
 >
 > _TraitImpl_ :\
-> &nbsp;&nbsp; `unsafe`<sup>?</sup> `impl` [_Generics_]<sup>?</sup> `!`<sup>?</sup>
+> &nbsp;&nbsp; `unsafe`<sup>?</sup> `impl` [_GenericParams_]<sup>?</sup> `!`<sup>?</sup>
 >              [_TypePath_] `for` [_Type_]\
 > &nbsp;&nbsp; [_WhereClause_]<sup>?</sup>\
 > &nbsp;&nbsp; `{`\
@@ -206,7 +206,7 @@ attributes].
 
 [_ConstantItem_]: constant-items.md
 [_Function_]: functions.md
-[_Generics_]: generics.md
+[_GenericParams_]: generics.md
 [_InnerAttribute_]: ../attributes.md
 [_MacroInvocationSemi_]: ../macros.md#macro-invocation
 [_Method_]: associated-items.md#methods

diff --git a/src/items/structs.md b/src/items/structs.md
@@ -8,14 +8,14 @@
 > _StructStruct_ :\
 > &nbsp;&nbsp; `struct`
 >   [IDENTIFIER]&nbsp;
->   [_Generics_]<sup>?</sup>
+>   [_GenericParams_]<sup>?</sup>
 >   [_WhereClause_]<sup>?</sup>
 >   ( `{` _StructFields_<sup>?</sup> `}` | `;` )
 >
 > _TupleStruct_ :\
 > &nbsp;&nbsp; `struct`
 >   [IDENTIFIER]&nbsp;
->   [_Generics_]<sup>?</sup>
+>   [_GenericParams_]<sup>?</sup>
 >   `(` _TupleFields_<sup>?</sup> `)`
 >   [_WhereClause_]<sup>?</sup>
 >   `;`
@@ -82,7 +82,7 @@ particular layout using the [`repr` attribute].
 
 [_OuterAttribute_]: ../attributes.md
 [IDENTIFIER]: ../identifiers.md
-[_Generics_]: generics.md
+[_GenericParams_]: generics.md
 [_WhereClause_]: generics.md#where-clauses
 [_Visibility_]: ../visibility-and-privacy.md
 [_Type_]: ../types.md#type-expressions
diff --git a/src/items/traits.md b/src/items/traits.md
@@ -3,7 +3,7 @@
 > **<sup>Syntax</sup>**\
 > _Trait_ :\
 > &nbsp;&nbsp; `unsafe`<sup>?</sup> `trait` [IDENTIFIER]&nbsp;
->              [_Generics_]<sup>?</sup>
+>              [_GenericParams_]<sup>?</sup>
 >              ( `:` [_TypeParamBounds_]<sup>?</sup> )<sup>?</sup>
 >              [_WhereClause_]<sup>?</sup> `{`\
 > &nbsp;&nbsp;&nbsp;&nbsp; [_InnerAttribute_]<sup>\*</sup>\
@@ -26,12 +26,12 @@
 > &nbsp;&nbsp; &nbsp;&nbsp; _TraitMethodDecl_ ( `;` | [_BlockExpression_] )
 >
 > _TraitFunctionDecl_ :\
-> &nbsp;&nbsp; [_FunctionQualifiers_] `fn` [IDENTIFIER]&nbsp;[_Generics_]<sup>?</sup>\
+> &nbsp;&nbsp; [_FunctionQualifiers_] `fn` [IDENTIFIER]&nbsp;[_GenericParams_]<sup>?</sup>\
 > &nbsp;&nbsp; &nbsp;&nbsp; `(` _TraitFunctionParameters_<sup>?</sup> `)`\
 > &nbsp;&nbsp; &nbsp;&nbsp; [_FunctionReturnType_]<sup>?</sup> [_WhereClause_]<sup>?</sup>
 >
 > _TraitMethodDecl_ :\
-> &nbsp;&nbsp; [_FunctionQualifiers_] `fn` [IDENTIFIER]&nbsp;[_Generics_]<sup>?</sup>\
+> &nbsp;&nbsp; [_FunctionQualifiers_] `fn` [IDENTIFIER]&nbsp;[_GenericParams_]<sup>?</sup>\
 > &nbsp;&nbsp; &nbsp;&nbsp; `(` [_SelfParam_] (`,` _TraitFunctionParam_)<sup>\*</sup> `,`<sup>?</sup> `)`\
 > &nbsp;&nbsp; &nbsp;&nbsp; [_FunctionReturnType_]<sup>?</sup> [_WhereClause_]<sup>?</sup>
 >
@@ -339,7 +339,7 @@ fn main() {
 [_Expression_]: ../expressions.md
 [_FunctionQualifiers_]: functions.md
 [_FunctionReturnType_]: functions.md
-[_Generics_]: generics.md
+[_GenericParams_]: generics.md
 [_MacroInvocationSemi_]: ../macros.md#macro-invocation
 [_OuterAttribute_]: ../attributes.md
 [_InnerAttribute_]: ../attributes.md

diff --git a/src/items/type-aliases.md b/src/items/type-aliases.md
@@ -2,7 +2,7 @@
 
 > **<sup>Syntax</sup>**\
 > _TypeAlias_ :\
-> &nbsp;&nbsp; `type` [IDENTIFIER]&nbsp;[_Generics_]<sup>?</sup>
+> &nbsp;&nbsp; `type` [IDENTIFIER]&nbsp;[_GenericParams_]<sup>?</sup>
 >              [_WhereClause_]<sup>?</sup> `=` [_Type_] `;`
 
 A _type alias_ defines a new name for an existing [type]. Type aliases are
@@ -33,6 +33,6 @@ let _ = TypeAlias(5); // Doesn't work
 ```
 
 [IDENTIFIER]: ../identifiers.md
-[_Generics_]: generics.md
+[_GenericParams_]: generics.md
 [_WhereClause_]: generics.md#where-clauses
 [_Type_]: ../types.md#type-expressions
diff --git a/src/items/unions.md b/src/items/unions.md
@@ -2,7 +2,7 @@
 
 > **<sup>Syntax</sup>**\
 > _Union_ :\
-> &nbsp;&nbsp; `union` [IDENTIFIER]&nbsp;[_Generics_]<sup>?</sup> [_WhereClause_]<sup>?</sup>
+> &nbsp;&nbsp; `union` [IDENTIFIER]&nbsp;[_GenericParams_]<sup>?</sup> [_WhereClause_]<sup>?</sup>
 >   `{`[_StructFields_] `}`
 
 A union declaration uses the same syntax as a struct declaration, except with
@@ -177,7 +177,7 @@ generics, trait implementations, inherent implementations, coherence, pattern
 checking, etc etc etc).
 
 [IDENTIFIER]: ../identifiers.md
-[_Generics_]: generics.md
+[_GenericParams_]: generics.md
 [_WhereClause_]: generics.md#where-clauses
 [_StructFields_]: structs.md
 [`transmute`]: ../../std/mem/fn.transmute.html

diff --git a/src/paths.md b/src/paths.md
@@ -50,37 +50,17 @@ mod m {
 >
 > _GenericArgs_ :\
 > &nbsp;&nbsp; &nbsp;&nbsp; `<` `>`\
-> &nbsp;&nbsp; | `<` _GenericArgsLifetimes_ `,`<sup>?</sup> `>`\
-> &nbsp;&nbsp; | `<` _GenericArgsTypes_ `,`<sup>?</sup> `>`\
-> &nbsp;&nbsp; | `<` _GenericArgsConsts_ `,`<sup>?</sup> `>`\
-> &nbsp;&nbsp; | `<` _GenericArgsBindings_ `,`<sup>?</sup> `>`\
-> &nbsp;&nbsp; | `<` _GenericArgsLifetimes_ `,` _GenericArgsTypes_ `,`<sup>?</sup> `>`\
-> &nbsp;&nbsp; | `<` _GenericArgsLifetimes_ `,` _GenericArgsConsts_ `,`<sup>?</sup> `>`\
-> &nbsp;&nbsp; | `<` _GenericArgsLifetimes_ `,` _GenericArgsBindings_ `,`<sup>?</sup> `>`\
-> &nbsp;&nbsp; | `<` _GenericArgsLifetimes_ `,` _GenericArgsTypes_ `,` _GenericArgsConsts_ `,`<sup>?</sup> `>`\
-> &nbsp;&nbsp; | `<` _GenericArgsLifetimes_ `,` _GenericArgsTypes_ `,` _GenericArgsBindings_ `,`<sup>?</sup> `>`\
-> &nbsp;&nbsp; | `<` _GenericArgsLifetimes_ `,` _GenericArgsConsts_ `,` _GenericArgsBindings_ `,`<sup>?</sup> `>`\
-> &nbsp;&nbsp; | `<` _GenericArgsTypes_ `,` _GenericArgsConsts_ `,` _GenericArgsBindings_ `,`<sup>?</sup> `>`\
-> &nbsp;&nbsp; | `<` _GenericArgsLifetimes_ `,` _GenericArgsTypes_ `,` _GenericArgsConsts_ `,` _GenericArgsBindings_ `,`<sup>?</sup> `>`
+> &nbsp;&nbsp; | `<` ( _GenericArg_ `,` )<sup>\*</sup> _GenericArg_ `,`<sup>?</sup> `>`
 >
-> _GenericArgsLifetimes_ :\
-> &nbsp;&nbsp; [_Lifetime_] (`,` [_Lifetime_])<sup>\*</sup>
->
-> _GenericArgsTypes_ :\
-> &nbsp;&nbsp; [_Type_] (`,` [_Type_])<sup>\*</sup>
->
-> _GenericArgsConsts_ :\
-> &nbsp;&nbsp; _GenericArgsConst_ (`,` _GenericArgsConst_)<sup>\*</sup>
+> _GenericArg_ :\
+> &nbsp;&nbsp; [_Lifetime_] | [_Type_] | _GenericArgsConst_ | _GenericArgsBinding_
 >
 > _GenericArgsConst_ :\
 > &nbsp;&nbsp; &nbsp;&nbsp; [_BlockExpression_]\
 > &nbsp;&nbsp; | [_LiteralExpression_]\
 > &nbsp;&nbsp; | `-` [_LiteralExpression_]\
 > &nbsp;&nbsp; | [_SimplePathSegment_]
 >
-> _GenericArgsBindings_ :\
-> &nbsp;&nbsp; _GenericArgsBinding_ (`,` _GenericArgsBinding_)<sup>\*</sup>
->
 > _GenericArgsBinding_ :\
 > &nbsp;&nbsp; [IDENTIFIER] `=` [_Type_]
 
@@ -95,6 +75,9 @@ ambiguity with the less-than operator. This is colloquially known as "turbofish"
 Vec::<u8>::with_capacity(1024);
 ```
 
+The order of generic arguments is restricted to lifetime arguments, then type
+arguments, then const arguments, then equality constraints.
+
 Const arguments must be surrounded by braces unless they are a
 [literal] or a single segment path.