Attributes: Docs about what's allowed where for block exprs, impls

Author: Havvy

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.
@@ -557,6 +559,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
@@ -569,4 +572,4 @@ You can implement `derive` for your own type through [procedural macros].
 [modules]: items/modules.html
 [statements]: statements.html
 [match expressions]: expressions/match-expr.html
-[external blocks]: items/external-blocks.html
+[external blocks]: items/external-blocks.html

src/expressions/block-expr.md

@@ -57,9 +57,30 @@ 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() {
+    #[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
+[value expressions]: expressions.html#place-expressions-and-value-expressions
+[outer attributes]: attributes.html
+[inner attributes]: attributes.html
+[expression statement]: statements.html#expression-statements

src/items/implementations.md

@@ -136,11 +136,17 @@ impl Seq<bool> 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