From 57bfd18d00784e37103be39f1132642ffefd86e4 Mon Sep 17 00:00:00 2001 From: Havvy Date: Mon, 4 Jun 2018 01:48:25 -0700 Subject: [PATCH 1/9] Attributes: Change ordering of general information. --- src/attributes.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/src/attributes.md b/src/attributes.md index 5ffb5de80..07e5f818f 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -21,11 +21,12 @@ >    | _MetaItem_\ >    | _MetaItem_ `,` _MetaSeq_ -Any [item declaration] or [generic lifetime or type parameter][generics] may -have an attribute applied to it. Attributes are modeled on Attributes in -[ECMA-335], with the syntax coming from [ECMA-334] \(C#). An _attribute_ is a +An _attribute_ is a general, free-form metadatum that is interpreted according to name, convention, -and language and compiler version. Attributes may appear as any of: +and language and compiler version. Attributes are modeled on Attributes in +[ECMA-335], with the syntax coming from [ECMA-334] \(C#). + +Attributes may appear as any of: * A single identifier, the attribute name * An identifier followed by the equals sign '=' and a literal, providing a @@ -39,6 +40,9 @@ item that the attribute is declared within. _Outer attributes_, written without the bang after the hash, apply to the item or generic parameter that follow the attribute. +Any [item declaration] or [generic lifetime or type parameter][generics] may +have an attribute applied to it. + An example of attributes: ```rust From 169fb5f487075714dd7f82892c6152ac66c80197 Mon Sep 17 00:00:00 2001 From: Havvy Date: Mon, 4 Jun 2018 01:59:43 -0700 Subject: [PATCH 2/9] List where attributes are accepted and which kind (outer/inner) --- src/attributes.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/src/attributes.md b/src/attributes.md index 07e5f818f..d0cd94341 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -40,8 +40,14 @@ item that the attribute is declared within. _Outer attributes_, written without the bang after the hash, apply to the item or generic parameter that follow the attribute. -Any [item declaration] or [generic lifetime or type parameter][generics] may -have an attribute applied to it. +Attributes may be applied to many things in the language: + +* All [item declarations] accept outer attributes while [external blocks], + [functions], [implementations], and [modules] accept inner attributes. +* [Statements] accept outer attributes. +* [Enum] variants and [struct] and [union] fields accept outer attributes. +* [Match expression arms][match expressions] accept outer attributes. +* [Generic lifetime or type parameter][generics] accept outer attributes. An example of attributes: @@ -543,5 +549,10 @@ You can implement `derive` for your own type through [procedural macros]. [zero-variant enum]: items/enumerations.html#zero-variant-enums [ECMA-334]: https://www.ecma-international.org/publications/standards/Ecma-334.htm [ECMA-335]: https://www.ecma-international.org/publications/standards/Ecma-335.htm -[item declaration]: items.html +[item declarations]: items.html [generics]: items/generics.html +[implementations]: items/implementations.html +[modules]: items/modules.html +[statements]: statements.html +[match expressions]: expressions/match-expr.html +[external blocks]: items/external-blocks.html \ No newline at end of file From 1c16ff417ae3daa313b510182fd5ee202d23f48c Mon Sep 17 00:00:00 2001 From: Havvy Date: Mon, 4 Jun 2018 02:31:42 -0700 Subject: [PATCH 3/9] Point out where general/specific attribute docs split --- src/attributes.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/attributes.md b/src/attributes.md index d0cd94341..60e51eb04 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -28,7 +28,7 @@ and language and compiler version. Attributes are modeled on Attributes in Attributes may appear as any of: -* A single identifier, the attribute name +* A single identifier, the _attribute name_ * An identifier followed by the equals sign '=' and a literal, providing a key/value pair * An identifier followed by a parenthesized literal, providing a @@ -72,6 +72,9 @@ mod bar { type int8_t = i8; ``` +The rest of this page describes or links to descriptions of which attribute +names have meaning. + ## Crate-only attributes - `crate_name` - specify the crate's crate name. From c03ca3c189c777f39917997720b598ebcba1407d Mon Sep 17 00:00:00 2001 From: Havvy Date: Mon, 4 Jun 2018 02:42:08 -0700 Subject: [PATCH 4/9] Add an example for outer attributes --- src/attributes.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/src/attributes.md b/src/attributes.md index 60e51eb04..62e1096a8 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -49,7 +49,7 @@ Attributes may be applied to many things in the language: * [Match expression arms][match expressions] accept outer attributes. * [Generic lifetime or type parameter][generics] accept outer attributes. -An example of attributes: +Some examples of attributes: ```rust // General metadata applied to the enclosing module or crate. @@ -70,6 +70,15 @@ mod bar { // A lint attribute used to suppress a warning/error #[allow(non_camel_case_types)] type int8_t = i8; + +// Outer attribute applies to the entire function. +fn some_unused_variables() { + #![allow(unused_variables)] + + let x = (); + let y = (); + let z = (); +} ``` The rest of this page describes or links to descriptions of which attribute From bf345ab7c245632fb56beb6feb5b8f7720c8c557 Mon Sep 17 00:00:00 2001 From: Havvy Date: Mon, 4 Jun 2018 03:14:24 -0700 Subject: [PATCH 5/9] Functions - Mention where inner attributes are allowed --- src/items/functions.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/src/items/functions.md b/src/items/functions.md index deff960c8..a3252add2 100644 --- a/src/items/functions.md +++ b/src/items/functions.md @@ -115,6 +115,21 @@ As non-Rust calling conventions do not support unwinding, unwinding past the end of an extern function will cause the process to abort. In LLVM, this is implemented by executing an illegal instruction. +## Function attributes + +Inner [attributes] on the function's block apply to the function item as a whole. + +For example, this function will only be available while running tests. + +``` +fn test_only() { + #![test] +} +``` + +> Note: Except for lints, it is idiomatic to only use outer attributes on +> function items. + [external blocks]: items/external-blocks.html [path]: paths.html [block]: expressions/block-expr.html @@ -122,3 +137,4 @@ implemented by executing an illegal instruction. [type]: types.html [*function item type*]: types.html#function-item-types [Trait]: items/traits.html +[attributes]: attributes.html From e13679e2faca939cbc461f7819f5da88a055353d Mon Sep 17 00:00:00 2001 From: Havvy Date: Mon, 4 Jun 2018 03:20:45 -0700 Subject: [PATCH 6/9] Impls - Mention where inner attrs are allowed --- src/items/implementations.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/items/implementations.md b/src/items/implementations.md index c5e722f90..5c6e1be56 100644 --- a/src/items/implementations.md +++ b/src/items/implementations.md @@ -136,5 +136,11 @@ impl Seq for u32 { } ``` +## Attributes in Implementations + +Implementations may contain inner [attributes] inside the brackets that contain +the associated items. They must come before the associated items. + [trait]: items/traits.html +[attributes]: attributes.html From 29bb2375ab53fdb596379fd63851704afd4b0b7b Mon Sep 17 00:00:00 2001 From: Havvy Date: Mon, 4 Jun 2018 03:38:20 -0700 Subject: [PATCH 7/9] Match arm takes outer attributes in match exprs --- src/expressions/match-expr.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/expressions/match-expr.md b/src/expressions/match-expr.md index a74ace0f5..382042079 100644 --- a/src/expressions/match-expr.md +++ b/src/expressions/match-expr.md @@ -175,6 +175,11 @@ let message = match maybe_digit { }; ``` +## Attributes on match arms + +Outer attributes are allowed on match arms. The only attributes that have +meaning on match arms are [`cfg`], `cold`, and the [lint check attributes]. + [_Expression_]: expressions.html [_BlockExpression_]: expressions/block-expr.html#block-expressions [place expression]: expressions.html#place-expressions-and-value-expressions @@ -183,3 +188,5 @@ let message = match maybe_digit { [numeric types]: types.html#numeric-types [_InnerAttribute_]: attributes.html [_OuterAttribute_]: attributes.html +[`cfg`]: attributes.html#conditional-compilation +[lint check attributes]: attributes.html#lint-check-attributes From 854ac935937980b4815e78a0f13e43c1f008d4e4 Mon Sep 17 00:00:00 2001 From: Havvy Date: Sun, 10 Jun 2018 00:32:34 -0700 Subject: [PATCH 8/9] Attributes: Docs about what's allowed where for block exprs, impls --- src/attributes.md | 11 +++++++---- src/expressions/block-expr.md | 23 +++++++++++++++++++++++ src/items/implementations.md | 14 ++++++++++---- 3 files changed, 40 insertions(+), 8 deletions(-) diff --git a/src/attributes.md b/src/attributes.md index 62e1096a8..d6baf723e 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -21,10 +21,9 @@ >    | _MetaItem_\ >    | _MetaItem_ `,` _MetaSeq_ -An _attribute_ is a -general, free-form metadatum that is interpreted according to name, convention, -and language and compiler version. Attributes are modeled on Attributes in -[ECMA-335], with the syntax coming from [ECMA-334] \(C#). +An _attribute_ is a general, free-form metadatum that is interpreted according +to name, convention, and language and compiler version. Attributes are modeled +on Attributes in [ECMA-335], with the syntax coming from [ECMA-334] \(C#). Attributes may appear as any of: @@ -45,6 +44,9 @@ Attributes may be applied to many things in the language: * All [item declarations] accept outer attributes while [external blocks], [functions], [implementations], and [modules] accept inner attributes. * [Statements] accept outer attributes. +* [Block expressions] accept outer and inner attributes, but only when they are + the outer expression of an [expression statement] or the final expression of + another block expression. * [Enum] variants and [struct] and [union] fields accept outer attributes. * [Match expression arms][match expressions] accept outer attributes. * [Generic lifetime or type parameter][generics] accept outer attributes. @@ -555,6 +557,7 @@ You can implement `derive` for your own type through [procedural macros]. [expression statement]: statements.html#expression-statements [call expression]: expressions/call-expr.html [block expression]: expressions/block-expr.html +[block expressions]: expressions/block-expr.html [`Drop`]: special-types-and-traits.html#drop [let statement]: statements.html#let-statements [unstable book plugin]: ../unstable-book/language-features/plugin.html#lint-plugins diff --git a/src/expressions/block-expr.md b/src/expressions/block-expr.md index a0ae19b68..d702a60aa 100644 --- a/src/expressions/block-expr.md +++ b/src/expressions/block-expr.md @@ -57,9 +57,32 @@ unsafe { let a = unsafe { f() }; ``` +## Attributes on block expressions + +Block expressions allow [outer attributes] and [inner attributes] directly after +the opening brace when the block expression is the outer expression of an +[expression statement] or the final expression of another block expression. The +attributes that have meaning on a block expression are [`cfg`], and [the lint +check attributes]. + +For example, this function returns `true` on unix platforms and `false` on other +platforms. + +```rust +fn is_unix_platform() -> bool { + #[cfg(unix)] { true } + #[cfg(not(unix))] { false } +} +``` + [_InnerAttribute_]: attributes.html [_Statement_]: statements.html [_Expression_]: expressions.html [expression]: expressions.html [statements]: statements.html [value expressions]: expressions.html#place-expressions-and-value-expressions +[outer attributes]: attributes.html +[inner attributes]: attributes.html +[expression statement]: statements.html#expression-statements +[`cfg`]: attributes.html#conditional-compilation +[the lint check attributes]: attributes.html#lint-check-attributes.html diff --git a/src/items/implementations.md b/src/items/implementations.md index 5c6e1be56..fa6b83aac 100644 --- a/src/items/implementations.md +++ b/src/items/implementations.md @@ -136,11 +136,17 @@ impl Seq for u32 { } ``` -## Attributes in Implementations - -Implementations may contain inner [attributes] inside the brackets that contain -the associated items. They must come before the associated items. +## Attributes on Implementations +Implementations may contain outer [attributes] before the `impl` keyword and +inner [attributes] inside the brackets that contain the associated items. Inner +attributes must come before any associated items. That attributes that have +meaning here are [`cfg`], [`deprecated`], [`doc`], and [the lint check +attributes]. [trait]: items/traits.html [attributes]: attributes.html +[`cfg`]: attributes.html#conditional-compilation +[`deprecated`]: attributes.html#deprecation +[`doc`]: attributes.html#documentation +[the lint check attributes]: attributes.html#lint-check-attributes.html From 4016b065cf13b30bb8b08cb51de34a15a747eac5 Mon Sep 17 00:00:00 2001 From: Havvy Date: Sun, 10 Jun 2018 01:30:22 -0700 Subject: [PATCH 9/9] Doc which attributes are allowed on statements --- src/statements.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/src/statements.md b/src/statements.md index 6d589b0fd..6bd713e4f 100644 --- a/src/statements.md +++ b/src/statements.md @@ -90,6 +90,11 @@ if true { }; ``` +## Attributes on Statements + +Statements accept [outer attributes]. The attributes that have meaning on a +statement are [`cfg`], and [the lint check attributes]. + [block]: expressions/block-expr.html [expression]: expressions.html [function]: items/functions.html @@ -97,4 +102,7 @@ if true { [module]: items/modules.html [canonical path]: paths.html#canonical-paths [implementations]: items/implementations.html -[variables]: variables.html \ No newline at end of file +[variables]: variables.html +[outer attributes]: attributes.html +[`cfg`]: attributes.html#conditional-compilation +[the lint check attributes]: attributes.html#lint-check-attributes.html