Grammar: Functions, methods, impl, traits, extern.

These all are intertwined with the "function" definition. Updates grammar for:
- Functions and methods
- Extern blocks
- Implementation
- Traits

Author: ehuss

src/items/external-blocks.md

@@ -1,5 +1,31 @@
 # External blocks
 
+> **<sup>Syntax</sup>**\
+> _ExternBlock_ :\
+> &nbsp;&nbsp; `extern` [_Abi_]<sup>?</sup> `{`\
+> &nbsp;&nbsp; &nbsp;&nbsp; [_InnerAttribute_]<sup>\*</sup>\
+> &nbsp;&nbsp; &nbsp;&nbsp; _ExternalItem_<sup>\*</sup>\
+> &nbsp;&nbsp; `}`
+>
+> _ExternalItem_ :\
+> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup>\
+> &nbsp;&nbsp; [_Visibility_]<sup>?</sup>\
+> &nbsp;&nbsp; ( _ExternalStaticItem_ | _ExternalFunctionItem_ )
+>
+> _ExternalStaticItem_ :\
+> &nbsp;&nbsp; `static` `mut`<sup>?</sup> [IDENTIFIER] `:` [_Type_] `;`
+>
+> _ExternalFunctionItem_ :\
+> &nbsp;&nbsp; `fn` [IDENTIFIER]&nbsp;[_Generics_]<sup>?</sup>\
+> &nbsp;&nbsp; `(` [_FunctionParameters_]<sup>?</sup> | _FunctionParametersWithVariadics_ ) `)`\
+> &nbsp;&nbsp; [_FunctionReturnType_]<sup>?</sup> [_WhereClause_]<sup>?</sup> `;`
+>
+> _FunctionParametersWithVariadics_ :\
+> &nbsp;&nbsp; ( [_FunctionParam_] `,` )<sup>\*</sup> _VariadicFunctionParam_
+>
+> _VariadicFunctionParam_ :\
+> &nbsp;&nbsp; [_FunctionParam_] `,` `...`
+
 External blocks form the basis for Rust's foreign function interface.
 Declarations in an external block describe symbols in external, non-Rust
 libraries.
@@ -23,8 +49,6 @@ extern {
 
 A number of [attributes] control the behavior of external blocks.
 
-[attributes]: attributes.html#ffi-attributes
-
 By default external blocks assume that the library they are calling uses the
 standard C ABI on the specific platform. Other ABIs may be specified using an
 `abi` string, as shown here:
@@ -81,3 +105,16 @@ It is valid to add the `link` attribute on an empty extern block. You can use
 this to satisfy the linking requirements of extern blocks elsewhere in your
 code (including upstream crates) instead of adding the attribute to each extern
 block.
+
+[IDENTIFIER]: identifiers.html
+[_Abi_]: items/functions.html
+[_FunctionParam_]: items/functions.html
+[_FunctionParameters_]: items/functions.html
+[_FunctionReturnType_]: items/functions.html
+[_Generics_]: items/generics.html
+[_InnerAttribute_]: attributes.html
+[_OuterAttribute_]: attributes.html
+[_Type_]: types.html
+[_Visibility_]: visibility-and-privacy.html
+[_WhereClause_]: items/generics.html#where-clauses
+[attributes]: attributes.html#ffi-attributes

src/items/functions.md

@@ -1,5 +1,33 @@
 # Functions
 
+> **<sup>Syntax</sup>**\
+> _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_
+>
+> _FunctionFront_:\
+> &nbsp;&nbsp; `unsafe`<sup>?</sup> (`extern` _Abi_<sup>?</sup>)<sup>?</sup>
+>
+> _Abi_:\
+> &nbsp;&nbsp; [STRING_LITERAL] | [RAW_STRING_LITERAL]
+>
+> _FunctionParameters_:\
+> &nbsp;&nbsp; _FunctionParam_ (`,` _FunctionParam_)<sup>\*</sup> `,`<sup>?</sup>
+>
+> _FunctionParam_ :\
+> &nbsp;&nbsp; [_Pattern_] `:` [_Type_]
+>
+> _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
 keyword `fn`. Functions may declare a set of *input* [*variables*][variables]
@@ -138,6 +166,15 @@ attributes], [`must_use`], [the procedural macro attributes], [the testing
 attributes], and [the optimization hint
 attributes].
 
+[IDENTIFIER]: identifiers.html
+[RAW_STRING_LITERAL]: tokens.html#raw-string-literals
+[STRING_LITERAL]: tokens.html#string-literals
+[_Generics_]: items/generics.html
+[_InnerAttribute_]: attributes.html
+[_Pattern_]: patterns.html
+[_Statement_]: statements.html
+[_Type_]: types.html
+[_WhereClause_]: items/generics.html#where-clauses
 [external blocks]: items/external-blocks.html
 [path]: paths.html
 [block]: expressions/block-expr.html

src/items/implementations.md

@@ -1,5 +1,49 @@
 # Implementations
 
+> **<sup>Syntax</sup>**\
+> _Implementation_ :\
+> &nbsp;&nbsp; _InherentImpl_ | _TraitImpl_
+>
+> _InherentImpl_ :\
+> &nbsp;&nbsp; `impl` [_GenericsDecl_] [_Type_] [_WhereClause_]<sup>?</sup> `{`\
+> &nbsp;&nbsp; &nbsp;&nbsp; [_InnerAttribute_]<sup>\*</sup>\
+> &nbsp;&nbsp; &nbsp;&nbsp; _InherentImplItem_<sup>\*</sup>\
+> &nbsp;&nbsp; `}`
+>
+> _InherentImplItem_ :\
+> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup>\
+> &nbsp;&nbsp; [_Visibility_]<sup>?</sup>\
+> &nbsp;&nbsp; ( [_ConstantItem_] | _Method_ )
+>
+> _TraitImpl_ :\
+> &nbsp;&nbsp; `unsafe`<sup>?</sup> `impl` [_GenericsDecl_] `!`<sup>?</sup>
+>              [_TypePath_] `for` [_Type_]\
+> &nbsp;&nbsp; [_WhereClause_]<sup>?</sup>\
+> &nbsp;&nbsp; `{`\
+> &nbsp;&nbsp; &nbsp;&nbsp; [_InnerAttribute_]<sup>\*</sup>\
+> &nbsp;&nbsp; &nbsp;&nbsp; _TraitImplItem_<sup>\*</sup>\
+> &nbsp;&nbsp; `}`
+>
+> _ImplItem_ :\
+> &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>
+
 An _implementation_ is an item that associates items with an _implementing type_.
 Implementations are defined with the keyword `impl` and contain functions
 that belong to an instance of the type that is being implemented or to the
@@ -59,6 +103,9 @@ The path to the associated items is `<` followed by a path to the implementing
 type followed by `as` followed by a path to the trait followed by `>` as a path
 component followed by the associated item's path component.
 
+[Unsafe traits] require the trait implementation to begin with the `unsafe`
+keyword.
+
 ```rust
 # #[derive(Copy, Clone)]
 # struct Point {x: f64, y: f64};
@@ -143,9 +190,26 @@ attributes must come before any associated items. That attributes that have
 meaning here are [`cfg`], [`deprecated`], [`doc`], and [the lint check
 attributes].
 
+[IDENTIFIER]: identifiers.html
+[_BlockWithInnerAttributes_]: items/functions.html
+[_ConstantItem_]: items/constant-items.html
+[_Generics_]: items/generics.html
+[_FunctionFront_]: items/functions.html
+[_FunctionParam_]: items/functions.html
+[_FunctionReturnType_]: items/functions.html
+[_GenericsDecl_]: types.html#type-parameters
+[_InnerAttribute_]: attributes.html
+[_Lifetime_]: trait-bounds.html
+[_OuterAttribute_]: attributes.html
+[_Type_]: types.html
+[_TypeAlias_]: items/type-aliases.html
+[_TypePath_]: paths.html#paths-in-types
+[_Visibility_]: visibility-and-privacy.html
+[_WhereClause_]: items/generics.html#where-clauses
 [trait]: items/traits.html
 [attributes]: attributes.html
 [`cfg`]: conditional-compilation.html
 [`deprecated`]: attributes.html#deprecation
 [`doc`]: attributes.html#documentation
 [the lint check attributes]: attributes.html#lint-check-attributes
+[Unsafe traits]: items/traits.html#unsafe-traits

src/items/traits.md

@@ -1,5 +1,25 @@
 # Traits
 
+> **<sup>Syntax</sup>**\
+> _Trait_ :\
+> &nbsp;&nbsp; `unsafe`<sup>?</sup> `trait` [IDENTIFIER]&nbsp;
+>              [_GenericsDecl_]<sup>?</sup>
+>              [_WhereClause_]<sup>?</sup> `{`\
+> &nbsp;&nbsp;&nbsp;&nbsp; _TraitItem_<sup>\*</sup>\
+> &nbsp;&nbsp; `}`
+>
+> _TraitItem_ :\
+> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> (_TraitMethod_ | _TraitConst_ | _TraitType_)
+>
+> _TraitMethod_ :\
+> &nbsp;&nbsp; [_MethodType_] `;` | [_Method_]
+>
+> _TraitConst_ :\
+> &nbsp;&nbsp; `const` [IDENTIFIER] ( ( `:` [_Type_] ) ( `=` [_Expression_] )<sup>?</sup> )<sup>?</sup> `;`
+>
+> _TraitType_ :\
+> &nbsp;&nbsp; `type` [IDENTIFIER] ( `:` [_TypeParamBounds_] )<sup>?</sup> `;`
+
 A _trait_ describes an abstract interface that types can implement. This
 interface consists of [associated items], which come in three varieties:
 
@@ -115,6 +135,23 @@ let circle = Box::new(circle) as Box<dyn Circle>;
 let nonsense = circle.radius() * circle.area();
 ```
 
+## Unsafe traits
+
+Traits 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.
+
+[`Sync`] and [`Send`] are examples of unsafe traits.
+
+[IDENTIFIER]: identifiers.html
+[_Expression_]: expressions.html
+[_GenericsDecl_]: types.html#type-parameters
+[_Method_]: items/implementations.html
+[_MethodType_]: items/implementations.html
+[_OuterAttribute_]: attributes.html
+[_TypeParamBounds_]: trait-bounds.html
+[_Type_]: types.html
+[_WhereClause_]: items/generics.html#where-clauses
 [bounds]: trait-bounds.html
 [trait object]: types.html#trait-objects
 [explicit]: expressions/operator-expr.html#type-cast-expressions
@@ -125,3 +162,7 @@ let nonsense = circle.radius() * circle.area();
 [generics]: items/generics.html
 [where clauses]: items/generics.html#where-clauses
 [generic functions]: items/functions.html#generic-functions
+[unsafe]: unsafety.html
+[trait implementation]: items/implementations.html#trait-implementations
+[`Send`]: special-types-and-traits.html#send
+[`Sync`]: special-types-and-traits.html#sync

src/unsafety.md

@@ -6,9 +6,15 @@ guarantees of Rust's static semantics.
 The following language level features cannot be used in the safe subset of
 Rust:
 
-- Dereferencing a [raw pointer](types.html#pointer-types).
-- Reading or writing a [mutable static variable](items/static-items.html#mutable-statics).
-- Reading a field of a [`union`](items/unions.html), or writing to a field of a
-  union that isn't [`Copy`](special-types-and-traits.html#copy).
+- Dereferencing a [raw pointer].
+- Reading or writing a [mutable static variable].
+- Reading a field of a [`union`], or writing to a field of a
+  union that isn't [`Copy`].
 - Calling an unsafe function (including an intrinsic or foreign function).
-- Implementing an unsafe trait.
+- Implementing an [unsafe trait].
+
+[`Copy`]: special-types-and-traits.html#copy
+[`union`]: items/unions.html
+[mutable static variable]: items/static-items.html#mutable-statics
+[raw pointer]: types.html#pointer-types
+[unsafe trait]: items/traits.html#unsafe-traits