Merge pull request #352 from Havvy/attr

General attribute docs improvements

Author: matthewjasper

src/attributes.md

@@ -21,13 +21,13 @@
 >    | _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
-general, free-form metadatum that is interpreted according to name, convention,
-and language and compiler version. Attributes may appear as any of:
+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#).
 
-* A single identifier, the attribute name
+Attributes may appear as any of:
+
+* 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
@@ -39,7 +39,19 @@ 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.
 
-An example of attributes:
+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.
+
+Some examples of attributes:
 
 ```rust
 // General metadata applied to the enclosing module or crate.
@@ -60,8 +72,20 @@ 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
+names have meaning.
+
 ## Crate-only attributes
 
 - `crate_name` - specify the crate's crate name.
@@ -533,11 +557,17 @@ 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
 [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

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

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

src/items/functions.md

@@ -115,10 +115,26 @@ 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
 [variables]: variables.html
 [type]: types.html
 [*function item type*]: types.html#function-item-types
 [Trait]: items/traits.html
+[attributes]: attributes.html

src/items/implementations.md

@@ -136,5 +136,17 @@ impl Seq<bool> for u32 {
 }
 ```
 
+## 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

src/statements.md

@@ -90,11 +90,19 @@ 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
 [item]: items.html
 [module]: items/modules.html
 [canonical path]: paths.html#canonical-paths
 [implementations]: items/implementations.html
-[variables]: variables.html
+[variables]: variables.html
+[outer attributes]: attributes.html
+[`cfg`]: attributes.html#conditional-compilation
+[the lint check attributes]: attributes.html#lint-check-attributes.html