Update functions:

ehuss · ehuss · commit 68a4efb931fa · 2018-10-01T19:46:18.000-07:00
- Review comments.
- Separate Function and Method in impl.
- Move _Method_ grammar to the section discussing methods.
- Be a little more explicit about `self` types.
- Fix block ending with expression for functions.
- Fix extern blocks not supporting patterns.
- Fix trait functions/methods having optional patterns, and the pattern restrictions.
diff --git a/src/items/associated-items.md b/src/items/associated-items.md
@@ -79,17 +79,31 @@ let _: f64 = f64::from_i32(42);
 
 ### Methods
 
+> _Method_ :\
+> &nbsp;&nbsp; [_FunctionFront_] `fn` [IDENTIFIER]&nbsp;[_Generics_]<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_]
+>
+> _SelfParam_ :\
+> &nbsp;&nbsp; &nbsp;&nbsp; (`&` | `&` [_Lifetime_])<sup>?</sup> `mut`<sup>?</sup> `self`\
+> &nbsp;&nbsp; | `mut`<sup>?</sup> `self` (`:` [_Type_])<sup>?</sup>
+
 Associated functions whose first parameter is named `self` are called *methods*
 and may be invoked using the [method call operator], for example, `x.foo()`, as
 well as the usual function call notation.
 
-The `self` parameter must have one of the following types. As a result, the
-following shorthands may be used to declare `self`:
+If the type of the `self` parameter is specified, it is limited to the type
+being implemented (or `Self`), or a reference or mutable reference to the
+type, or a boxed value of the type being implemented (such as `Box<Self>`).
+Shorthand syntax can be used without specifying a type, which have the
+following equivalents:
 
-* `self` -> `self: Self`
-* `&'lifetime self` -> `self: &'lifetime Self`
-* `&'lifetime mut self` -> `self: &'lifetime mut Self`
-* `self : Box<Self>` (no shorthand)
+Shorthand             | Equivalent
+----------------------|-----------
+`self`                | `self: Self`
+`&'lifetime self`     | `self: &'lifetime Self`
+`&'lifetime mut self` | `self: &'lifetime mut Self`
 
 > Note: Lifetimes can be and usually are elided with this shorthand.
 
@@ -272,6 +286,14 @@ fn main() {
 }
 ```
 
+[_BlockExpression_]: expressions/block-expr.html
+[_FunctionFront_]: items/functions.html
+[_FunctionParam_]: items/functions.html
+[_FunctionReturnType_]: items/functions.html
+[_Generics_]: items/generics.html
+[_Lifetime_]: trait-bounds.html
+[_Type_]: types.html
+[_WhereClause_]: items/generics.html#where-clauses
 [trait]: items/traits.html
 [traits]: items/traits.html
 [type aliases]: items/type-aliases.html
diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md
@@ -17,22 +17,26 @@
 >
 > _ExternalFunctionItem_ :\
 > &nbsp;&nbsp; `fn` [IDENTIFIER]&nbsp;[_Generics_]<sup>?</sup>\
-> &nbsp;&nbsp; `(` [_FunctionParameters_]<sup>?</sup> | _FunctionParametersWithVariadics_ ) `)`\
+> &nbsp;&nbsp; `(` _NamedFunctionParameters_<sup>?</sup> | _NamedFunctionParametersWithVariadics_ ) `)`\
 > &nbsp;&nbsp; [_FunctionReturnType_]<sup>?</sup> [_WhereClause_]<sup>?</sup> `;`
 >
-> _FunctionParametersWithVariadics_ :\
-> &nbsp;&nbsp; ( [_FunctionParam_] `,` )<sup>\*</sup> _VariadicFunctionParam_
+> _NamedFunctionParameters_ :\
+> &nbsp;&nbsp; _NamedFunctionParam_ ( `,` _NamedFunctionParam_ )<sup>\*</sup> `,`<sup>?</sup>
 >
-> _VariadicFunctionParam_ :\
-> &nbsp;&nbsp; [_FunctionParam_] `,` `...`
+> _NamedFunctionParam_ :\
+> &nbsp;&nbsp; ( [IDENTIFIER] | `_` ) `:` [_Type_]
+>
+> _NamedFunctionParametersWithVariadics_ :\
+> &nbsp;&nbsp; ( _NamedFunctionParam_ `,` )<sup>\*</sup> _NamedFunctionParam_ `,` `...`
 
 External blocks form the basis for Rust's foreign function interface.
 Declarations in an external block describe symbols in external, non-Rust
 libraries.
 
 Functions within external blocks are declared in the same way as other Rust
 functions, with the exception that they may not have a body and are instead
-terminated by a semicolon.
+terminated by a semicolon. Patterns are not allowed in parameters, only
+[IDENTIFIER] or `_` may be used.
 
 Functions within external blocks may be called by Rust code, just like
 functions defined in Rust. The Rust compiler automatically translates between
diff --git a/src/items/functions.md b/src/items/functions.md
@@ -1,32 +1,26 @@
 # Functions
 
 > **<sup>Syntax</sup>**\
-> _Function_:\
+> _Function_ :\
 > &nbsp;&nbsp; _FunctionFront_ `fn` [IDENTIFIER]&nbsp;[_Generics_]<sup>?</sup>\
 > &nbsp;&nbsp; &nbsp;&nbsp; `(` _FunctionParameters_<sup>?</sup> `)`\
 > &nbsp;&nbsp; &nbsp;&nbsp; _FunctionReturnType_<sup>?</sup> [_WhereClause_]<sup>?</sup>\
-> &nbsp;&nbsp; &nbsp;&nbsp; _BlockWithInnerAttributes_
+> &nbsp;&nbsp; &nbsp;&nbsp; [_BlockExpression_]
 >
-> _FunctionFront_:\
+> _FunctionFront_ :\
 > &nbsp;&nbsp; `unsafe`<sup>?</sup> (`extern` _Abi_<sup>?</sup>)<sup>?</sup>
 >
-> _Abi_:\
+> _Abi_ :\
 > &nbsp;&nbsp; [STRING_LITERAL] | [RAW_STRING_LITERAL]
 >
-> _FunctionParameters_:\
+> _FunctionParameters_ :\
 > &nbsp;&nbsp; _FunctionParam_ (`,` _FunctionParam_)<sup>\*</sup> `,`<sup>?</sup>
 >
 > _FunctionParam_ :\
 > &nbsp;&nbsp; [_Pattern_] `:` [_Type_]
 >
-> _FunctionReturnType_:\
+> _FunctionReturnType_ :\
 > &nbsp;&nbsp; `->` [_Type_]
->
-> _BlockWithInnerAttributes_ :\
-> &nbsp;&nbsp; `{`\
-> &nbsp;&nbsp; &nbsp;&nbsp; [_InnerAttribute_]<sup>\*</sup>\
-> &nbsp;&nbsp; &nbsp;&nbsp; [_Statement_]<sup>\*</sup>\
-> &nbsp;&nbsp; `}`
 
 A _function_ consists of a [block], along with a name and a set of parameters.
 Other than a name, all these are optional. Functions are declared with the
@@ -169,6 +163,7 @@ attributes].
 [IDENTIFIER]: identifiers.html
 [RAW_STRING_LITERAL]: tokens.html#raw-string-literals
 [STRING_LITERAL]: tokens.html#string-literals
+[_BlockExpression_]: expressions/block-expr.html
 [_Generics_]: items/generics.html
 [_InnerAttribute_]: attributes.html
 [_Pattern_]: patterns.html
diff --git a/src/items/implementations.md b/src/items/implementations.md
@@ -13,7 +13,7 @@
 > _InherentImplItem_ :\
 > &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup>\
 > &nbsp;&nbsp; [_Visibility_]<sup>?</sup>\
-> &nbsp;&nbsp; ( [_ConstantItem_] | _Method_ )
+> &nbsp;&nbsp; ( [_ConstantItem_] | [_Function_] | [_Method_] )
 >
 > _TraitImpl_ :\
 > &nbsp;&nbsp; `unsafe`<sup>?</sup> `impl` [_Generics_] `!`<sup>?</sup>
@@ -27,22 +27,7 @@
 > _TraitImplItem_ :\
 > &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup>\
 > &nbsp;&nbsp; [_Visibility_]<sup>?</sup>\
-> &nbsp;&nbsp; ( [_TypeAlias_] | [_ConstantItem_] | _Method_ )
->
-> _Method_:\
-> &nbsp;&nbsp; _MethodType_ [_BlockWithInnerAttributes_]
->
-> _MethodType_:\
-> &nbsp;&nbsp; [_FunctionFront_] `fn` [IDENTIFIER]&nbsp;[_Generics_]<sup>?</sup>\
-> &nbsp;&nbsp; &nbsp;&nbsp; `(` _MethodParameters_<sup>?</sup> `)`\
-> &nbsp;&nbsp; &nbsp;&nbsp; [_FunctionReturnType_]<sup>?</sup> [_WhereClause_]<sup>?</sup>
->
-> _MethodParameters_:\
-> &nbsp;&nbsp; (_SelfParam_ | [_FunctionParam_] ) (`,` [_FunctionParam_])<sup>\*</sup> `,`<sup>?</sup>
->
-> _SelfParam_:\
-> &nbsp;&nbsp; &nbsp;&nbsp; (`&` | `&` [_Lifetime_])<sup>?</sup> `mut`<sup>?</sup> `self`\
-> &nbsp;&nbsp; | `mut`<sup>?</sup> `self` (`:` [_Type_])<sup>?</sup>
+> &nbsp;&nbsp; ( [_TypeAlias_] | [_ConstantItem_] | [_Function_] | [_Method_] )
 
 An _implementation_ is an item that associates items with an _implementing type_.
 Implementations are defined with the keyword `impl` and contain functions
@@ -191,18 +176,15 @@ meaning here are [`cfg`], [`deprecated`], [`doc`], and [the lint check
 attributes].
 
 [IDENTIFIER]: identifiers.html
-[_BlockWithInnerAttributes_]: items/functions.html
 [_ConstantItem_]: items/constant-items.html
-[_FunctionFront_]: items/functions.html
-[_FunctionParam_]: items/functions.html
-[_FunctionReturnType_]: items/functions.html
+[_Function_]: items/functions.html
 [_Generics_]: items/generics.html
 [_InnerAttribute_]: attributes.html
-[_Lifetime_]: trait-bounds.html
+[_Method_]: items/associated-items.html#methods
 [_OuterAttribute_]: attributes.html
-[_Type_]: types.html
 [_TypeAlias_]: items/type-aliases.html
 [_TypePath_]: paths.html#paths-in-types
+[_Type_]: types.html
 [_Visibility_]: visibility-and-privacy.html
 [_WhereClause_]: items/generics.html#where-clauses
 [trait]: items/traits.html
diff --git a/src/items/traits.md b/src/items/traits.md
@@ -9,10 +9,29 @@
 > &nbsp;&nbsp; `}`
 >
 > _TraitItem_ :\
-> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> (_TraitMethod_ | _TraitConst_ | _TraitType_)
+> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> (_TraitFunc_ | _TraitMethod_ | _TraitConst_ | _TraitType_)
+>
+> _TraitFunc_ :\
+> &nbsp;&nbsp; &nbsp;&nbsp; _TraitFunctionDecl_ ( `;` | [_BlockExpression_] )
 >
 > _TraitMethod_ :\
-> &nbsp;&nbsp; [_MethodType_] `;` | [_Method_]
+> &nbsp;&nbsp; &nbsp;&nbsp; _TraitMethodDecl_ ( `;` | [_BlockExpression_] )
+>
+> _TraitFunctionDecl_ :\
+> &nbsp;&nbsp; [_FunctionFront_] `fn` [IDENTIFIER]&nbsp;[_Generics_]<sup>?</sup>\
+> &nbsp;&nbsp; &nbsp;&nbsp; `(` _TraitFunctionParameters_<sup>?</sup> `)`\
+> &nbsp;&nbsp; &nbsp;&nbsp; [_FunctionReturnType_]<sup>?</sup> [_WhereClause_]<sup>?</sup>
+>
+> _TraitMethodDecl_ :\
+> &nbsp;&nbsp; [_FunctionFront_] `fn` [IDENTIFIER]&nbsp;[_Generics_]<sup>?</sup>\
+> &nbsp;&nbsp; &nbsp;&nbsp; `(` [_SelfParam_] (`,` _TraitFunctionParam_)<sup>\*</sup> `,`<sup>?</sup> `)`\
+> &nbsp;&nbsp; &nbsp;&nbsp; [_FunctionReturnType_]<sup>?</sup> [_WhereClause_]<sup>?</sup>
+>
+> _TraitFunctionParameters_ :\
+> &nbsp;&nbsp; _TraitFunctionParam_ (`,` _TraitFunctionParam_)<sup>\*</sup> `,`<sup>?</sup>
+>
+> _TraitFunctionParam_<sup>[†](#parameter-patterns)</sup> :\
+> &nbsp;&nbsp; ( [_Pattern_] `:` )<sup>?</sup> [_Type_]
 >
 > _TraitConst_ :\
 > &nbsp;&nbsp; `const` [IDENTIFIER] ( ( `:` [_Type_] ) ( `=` [_Expression_] )<sup>?</sup> )<sup>?</sup> `;`
@@ -137,18 +156,54 @@ let nonsense = circle.radius() * circle.area();
 
 ## Unsafe traits
 
-Traits that begin with the `unsafe` keyword indicate that *implementing* the
+Traits items that begin with the `unsafe` keyword indicate that *implementing* the
 trait may be [unsafe]. It is safe to use a correctly implemented unsafe trait.
-The [trait implementation] must also include the `unsafe` keyword.
+The [trait implementation] must also begin with the `unsafe` keyword.
 
 [`Sync`] and [`Send`] are examples of unsafe traits.
 
+## Parameter patterns
+
+The pattern for a trait function or method parameter is optional:
+
+```rust
+trait T {
+    fn f(i32);  // Parameter identifiers are not required.
+}
+```
+
+The kinds of patterns for parameters is limited to one of the following:
+
+* [IDENTIFIER]
+* `mut` [IDENTIFIER]
+* [`_`][WildcardPattern]
+* `&` [IDENTIFIER]
+* `&&` [IDENTIFIER]
+
+Function or method declarations without a body only allow [IDENTIFIER] or
+[wild card][WildcardPattern] patterns. `mut` [IDENTIFIER] is currently
+allowed, but it is deprecated and will become a hard error in the future.
+<!-- https://github.com/rust-lang/rust/issues/35203 -->
+
+<!-- 2018 changes:
+
+Function or method parameter patterns are no longer optional, and are required.
+
+All irrefutable pattern kinds are allowed (as long as there is a body).
+-->
+
+
 [IDENTIFIER]: identifiers.html
+[WildcardPattern]: patterns.html#wildcard-pattern
+[_BlockExpression_]: expressions/block-expr.html
 [_Expression_]: expressions.html
+[_FunctionFront_]: items/functions.html
+[_FunctionParam_]: items/functions.html
+[_FunctionReturnType_]: items/functions.html
 [_Generics_]: items/generics.html
-[_Method_]: items/implementations.html
-[_MethodType_]: items/implementations.html
 [_OuterAttribute_]: attributes.html
+[_Pattern_]: patterns.html
+[_SelfParam_]: items/associated-items.html#methods
 [_TypeParamBounds_]: trait-bounds.html
 [_Type_]: types.html
 [_WhereClause_]: items/generics.html#where-clauses
