Merge pull request #657 from c410-f3r/attrs-fn

Add reference for attributes in function parameters

Author: ehuss

src/attributes.md

@@ -50,6 +50,9 @@ Attributes may be applied to many things in the language:
 * [Generic lifetime or type parameter][generics] accept outer attributes.
 * Expressions accept outer attributes in limited situations, see [Expression
   Attributes] for details.
+* [Function][functions], [closure]] and [function pointer]
+  parameters accept outer attributes. This includes attributes on variadic parameters
+  denoted with `...` in function pointers and [external blocks][variadic functions].
 
 Some examples of attributes:
 
@@ -304,3 +307,6 @@ The following is an index of all built-in attributes.
 [statements]: statements.md
 [struct]: items/structs.md
 [union]: items/unions.md
+[closure]: expressions/closure-expr.md
+[function pointer]: types/function-pointer.md
+[variadic functions]: items/external-blocks.html#variadic-functions

src/expressions/closure-expr.md

@@ -10,7 +10,7 @@
 > &nbsp;&nbsp; _ClosureParam_ (`,` _ClosureParam_)<sup>\*</sup> `,`<sup>?</sup>
 >
 > _ClosureParam_ :\
-> &nbsp;&nbsp; [_Pattern_]&nbsp;( `:` [_Type_] )<sup>?</sup>
+> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> [_Pattern_]&nbsp;( `:` [_Type_] )<sup>?</sup>
 
 A _closure expression_ defines a closure and denotes it as a value, in a single
 expression. A closure expression is a pipe-symbol-delimited (`|`) list of
@@ -67,13 +67,20 @@ let word = "konnichiwa".to_owned();
 ten_times(move |j| println!("{}, {}", word, j));
 ```
 
+## Attributes on closure parameters
+
+Attributes on closure parameters follow the same rules and restrictions as
+[regular function parameters].
+
 [block]: block-expr.md
 [function definitions]: ../items/functions.md
 [patterns]: ../patterns.md
+[regular function parameters]: ../items/functions.md#attributes-on-function-parameters
 
 [_Expression_]: ../expressions.md
 [_BlockExpression_]: block-expr.md
 [_TypeNoBounds_]: ../types.md#type-expressions
 [_Pattern_]: ../patterns.md
 [_Type_]: ../types.md#type-expressions
 [`let` binding]: ../statements.md#let-statements
+[_OuterAttribute_]: ../attributes.md

src/items/associated-items.md

@@ -86,8 +86,13 @@ let _: f64 = f64::from_i32(42);
 >       [_BlockExpression_]
 >
 > _SelfParam_ :\
-> &nbsp;&nbsp; &nbsp;&nbsp; (`&` | `&` [_Lifetime_])<sup>?</sup> `mut`<sup>?</sup> `self`\
-> &nbsp;&nbsp; | `mut`<sup>?</sup> `self` (`:` [_Type_])<sup>?</sup>
+> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> ( _ShorthandSelf_ | _TypedSelf_ )
+>
+> _ShorthandSelf_ :\
+> &nbsp;&nbsp;  (`&` | `&` [_Lifetime_])<sup>?</sup> `mut`<sup>?</sup> `self`
+>
+> _TypedSelf_ :\
+> &nbsp;&nbsp; `mut`<sup>?</sup> `self` `:` [_Type_]
 
 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
@@ -190,6 +195,11 @@ let bounding_box = circle_shape.bounding_box();
 > methods with anonymous parameters (e.g. `fn foo(u8)`). This is deprecated and
 > an error as of the 2018 edition. All parameters must have an argument name.
 
+#### Attributes on method parameters
+
+Attributes on method parameters follow the same rules and restrictions as
+[regular function parameters].
+
 ## Associated Types
 
 *Associated types* are [type aliases] associated with another type. Associated
@@ -336,6 +346,7 @@ fn main() {
 [`Box<Self>`]: ../special-types-and-traits.md#boxt
 [`Pin<P>`]: ../special-types-and-traits.md#pinp
 [`Rc<Self>`]: ../special-types-and-traits.md#rct
+[_OuterAttribute_]: ../attributes.md
 [traits]: traits.md
 [type aliases]: type-aliases.md
 [inherent implementations]: implementations.md#inherent-implementations
@@ -349,3 +360,4 @@ fn main() {
 [function item]: ../types/function-item.md
 [method call operator]: ../expressions/method-call-expr.md
 [path]: ../paths.md
+[regular function parameters]: functions.md#attributes-on-function-parameters 

src/items/external-blocks.md

@@ -25,10 +25,10 @@
 > &nbsp;&nbsp; _NamedFunctionParam_ ( `,` _NamedFunctionParam_ )<sup>\*</sup> `,`<sup>?</sup>
 >
 > _NamedFunctionParam_ :\
-> &nbsp;&nbsp; ( [IDENTIFIER] | `_` ) `:` [_Type_]
+> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> ( [IDENTIFIER] | `_` ) `:` [_Type_]
 >
 > _NamedFunctionParametersWithVariadics_ :\
-> &nbsp;&nbsp; ( _NamedFunctionParam_ `,` )<sup>\*</sup> _NamedFunctionParam_ `,` `...`
+> &nbsp;&nbsp; ( _NamedFunctionParam_ `,` )<sup>\*</sup> _NamedFunctionParam_ `,` [_OuterAttribute_]<sup>\*</sup> `...`
 
 External blocks provide _declarations_ of items that are not _defined_ in the
 current crate and are the basis of Rust's foreign function interface. These are
@@ -163,6 +163,11 @@ extern {
 }
 ```
 
+### Attributes on function parameters
+
+Attributes on extern function parameters follow the same rules and
+restrictions as [regular function parameters].
+
 [IDENTIFIER]: ../identifiers.md
 [WebAssembly module]: https://webassembly.github.io/spec/core/syntax/modules.html
 [functions]: functions.md
@@ -179,3 +184,4 @@ extern {
 [_Visibility_]: ../visibility-and-privacy.md
 [_WhereClause_]: generics.md#where-clauses
 [attributes]: ../attributes.md
+[regular function parameters]: functions.md#attributes-on-function-parameters

src/items/functions.md

@@ -20,7 +20,7 @@
 > &nbsp;&nbsp; _FunctionParam_ (`,` _FunctionParam_)<sup>\*</sup> `,`<sup>?</sup>
 >
 > _FunctionParam_ :\
-> &nbsp;&nbsp; [_Pattern_] `:` [_Type_]
+> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> [_Pattern_] `:` [_Type_]
 >
 > _FunctionReturnType_ :\
 > &nbsp;&nbsp; `->` [_Type_]
@@ -345,12 +345,40 @@ fn test_only() {
 > Note: Except for lints, it is idiomatic to only use outer attributes on
 > function items.
 
-The attributes that have meaning on a function are [`cfg`], [`deprecated`],
+The attributes that have meaning on a function are [`cfg`], [`cfg_attr`], [`deprecated`],
 [`doc`], [`export_name`], [`link_section`], [`no_mangle`], [the lint check
 attributes], [`must_use`], [the procedural macro attributes], [the testing
 attributes], and [the optimization hint attributes]. Functions also accept
 attributes macros.
 
+## Attributes on function parameters
+
+[Outer attributes][attributes] are allowed on function parameters and the
+permitted [built-in attributes] are restricted to `cfg`, `cfg_attr`, `allow`,
+`warn`, `deny`, and `forbid`.
+
+```rust
+fn len(
+    #[cfg(windows)] slice: &[u16],
+    #[cfg(not(windows))] slice: &[u8],
+) -> usize {
+    slice.len()
+}
+```
+
+Inert helper attributes used by procedural macro attributes applied to items are also
+allowed but be careful to not include these inert attributes in your final `TokenStream`.
+
+For example, the following code defines an inert `some_inert_attribute` attribute that
+is not formally defined anywhere and the `some_proc_macro_attribute` procedural macro is
+responsible for detecting its presence and removing it from the output token stream.
+
+```rust,ignore
+#[some_proc_macro_attribute]
+fn foo_oof(#[some_inert_attribute] arg: u8) {
+}
+```
+
 [IDENTIFIER]: ../identifiers.md
 [RAW_STRING_LITERAL]: ../tokens.md#raw-string-literals
 [STRING_LITERAL]: ../tokens.md#string-literals
@@ -359,6 +387,7 @@ attributes macros.
 [_Pattern_]: ../patterns.md
 [_Type_]: ../types.md#type-expressions
 [_WhereClause_]: generics.md#where-clauses
+[_OuterAttribute_]: ../attributes.md
 [const context]: ../const_eval.md#const-context
 [external block]: external-blocks.md
 [path]: ../paths.md
@@ -368,7 +397,8 @@ attributes macros.
 [*function item type*]: ../types/function-item.md
 [Trait]: traits.md
 [attributes]: ../attributes.md
-[`cfg`]: ../conditional-compilation.md
+[`cfg`]: ../conditional-compilation.md#the-cfg-attribute
+[`cfg_attr`]: ../conditional-compilation.md#the-cfg_attr-attribute
 [the lint check attributes]: ../attributes/diagnostics.md#lint-check-attributes
 [the procedural macro attributes]: ../procedural-macros.md
 [the testing attributes]: ../attributes/testing.md
@@ -383,3 +413,4 @@ attributes macros.
 [`link_section`]: ../abi.md#the-link_section-attribute
 [`no_mangle`]: ../abi.md#the-no_mangle-attribute
 [external_block_abi]: external-blocks.md#abi
+[built-in attributes]: ../attributes.html#built-in-attributes-index

src/items/traits.md

@@ -38,7 +38,7 @@
 > &nbsp;&nbsp; _TraitFunctionParam_ (`,` _TraitFunctionParam_)<sup>\*</sup> `,`<sup>?</sup>
 >
 > _TraitFunctionParam_<sup>[†](#parameter-patterns)</sup> :\
-> &nbsp;&nbsp; ( [_Pattern_] `:` )<sup>?</sup> [_Type_]
+> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> ( [_Pattern_] `:` )<sup>?</sup> [_Type_]
 >
 > _TraitConst_ :\
 > &nbsp;&nbsp; `const` [IDENTIFIER] `:` [_Type_]&nbsp;( `=` [_Expression_] )<sup>?</sup> `;`

src/types/function-pointer.md

@@ -15,10 +15,10 @@
 > &nbsp;&nbsp; _MaybeNamedParam_ ( `,` _MaybeNamedParam_ )<sup>\*</sup> `,`<sup>?</sup>
 >
 > _MaybeNamedParam_ :\
-> &nbsp;&nbsp; ( ( [IDENTIFIER] | `_` ) `:` )<sup>?</sup> [_Type_]
+> &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> ( ( [IDENTIFIER] | `_` ) `:` )<sup>?</sup> [_Type_]
 >
 > _MaybeNamedFunctionParametersVariadic_ :\
-> &nbsp;&nbsp; ( _MaybeNamedParam_ `,` )<sup>\*</sup> _MaybeNamedParam_ `,` `...`
+> &nbsp;&nbsp; ( _MaybeNamedParam_ `,` )<sup>\*</sup> _MaybeNamedParam_ `,` [_OuterAttribute_]<sup>\*</sup> `...`
 
 Function pointer types, written using the `fn` keyword, refer to a function
 whose identity is not necessarily known at compile-time. They can be created
@@ -44,13 +44,20 @@ let bo: Binop = add;
 x = bo(5,7);
 ```
 
+## Attributes on function pointer parameters
+
+Attributes on function pointer parameters follow the same rules and
+restrictions as [regular function parameters].
+
 [IDENTIFIER]: ../identifiers.md
 [_ForLifetimes_]: ../items/generics.md#where-clauses
 [_FunctionQualifiers_]: ../items/functions.md
 [_TypeNoBounds_]: ../types.md#type-expressions
 [_Type_]: ../types.md#type-expressions
+[_OuterAttribute_]: ../attributes.md
 [`extern`]: ../items/external-blocks.md
 [closures]: closure.md
 [extern function]: ../items/functions.md#extern-function-qualifier
 [function items]: function-item.md
 [unsafe function]: ../unsafe-functions.md
+[regular function parameters]: ../items/functions.md#attributes-on-function-parameters