address review comments

src/SUMMARY.md

@@ -88,7 +88,6 @@
     - [Behavior not considered unsafe](behavior-not-considered-unsafe.md)
 
 - [Application Binary Interface](abi.md)
-  - [#[used]](used.md)
 
 [Appendix: Influences](influences.md)
 

src/abi.md

@@ -1,9 +1,60 @@
 # Application Binary Interface (ABI)
 
-This section documents (or will document) features that affect the ABI of a Rust program / binary,
-rlib, dylib, etc. A (likely incomplete) list of such features is shown below:
+This section documents features that affect the ABI of a Rust program / binary, rlib, dylib, etc. A
+list of such features is shown below:
 
-- #[used]
-- #[no_mangle]
-- #[link_section]
-- extern "$ABI" fn
+- `#[export_name]`
+- `#[link_section]`
+- `#[no_mangle]`
+- `#[used]`
+- `extern "$ABI" fn`
+
+## `#[used]`
+
+The `#[used]` attribute can only be applied to `static` variables. This attribute forces the
+compiler to keep the variable in the output object file (.o, .rlib, etc.) even if the variable is
+not used, or referenced, by any other item in the crate.
+
+Below is an example that shows under what conditions the compiler keeps a `static` variable in the
+output object file.
+
+``` rust
+// foo.rs
+
+#![feature(used)]
+
+// kept because of #[used]
+#[used]
+static FOO: u32 = 0;
+
+// removed because it's unused
+#[allow(dead_code)]
+static BAR: u32 = 0;
+
+// kept because it's referenced by a public, reachable function
+pub static BAZ: u32 = 0;
+
+pub static QUUX: u32 = 0;
+
+pub fn quux() -> &'static u32 {
+    &QUUX
+}
+
+// removed because it's referenced by a private, unused (dead) function
+static CORGE: u32 = 0;
+
+#[allow(dead_code)]
+fn corge() -> &'static u32 {
+    &CORGE
+}
+```
+
+``` console
+$ rustc -O --emit=obj --crate-type=rlib foo.rs
+
+$ nm -C foo.o
+0000000000000000 R foo::BAZ
+0000000000000000 r foo::FOO
+0000000000000000 R foo::QUUX
+0000000000000000 T foo::quux
+```

src/attributes.md

@@ -1,24 +1,24 @@
 # Attributes
 
-> **<sup>Syntax</sup>**  
-> _Attribute_ :  
-> &nbsp;&nbsp; _InnerAttribute_ | _OuterAttribute_  
->  
-> _InnerAttribute_ :  
-> &nbsp;&nbsp; `#![` MetaItem `]`  
->   
-> _OuterAttribute_ :  
-> &nbsp;&nbsp; `#[` MetaItem `]`  
->   
-> _MetaItem_ :  
-> &nbsp;&nbsp; &nbsp;&nbsp; IDENTIFIER  
-> &nbsp;&nbsp; | IDENTIFIER `=` LITERAL  
-> &nbsp;&nbsp; | IDENTIFIER `(` LITERAL `)`  
-> &nbsp;&nbsp; | IDENTIFIER `(` _MetaSeq_ `)`  
->   
-> _MetaSeq_ :  
-> &nbsp;&nbsp; &nbsp;&nbsp; EMPTY  
-> &nbsp;&nbsp; | _MetaItem_  
+> **<sup>Syntax</sup>**
+> _Attribute_ :
+> &nbsp;&nbsp; _InnerAttribute_ | _OuterAttribute_
+>
+> _InnerAttribute_ :
+> &nbsp;&nbsp; `#![` MetaItem `]`
+>
+> _OuterAttribute_ :
+> &nbsp;&nbsp; `#[` MetaItem `]`
+>
+> _MetaItem_ :
+> &nbsp;&nbsp; &nbsp;&nbsp; IDENTIFIER
+> &nbsp;&nbsp; | IDENTIFIER `=` LITERAL
+> &nbsp;&nbsp; | IDENTIFIER `(` LITERAL `)`
+> &nbsp;&nbsp; | IDENTIFIER `(` _MetaSeq_ `)`
+>
+> _MetaSeq_ :
+> &nbsp;&nbsp; &nbsp;&nbsp; EMPTY
+> &nbsp;&nbsp; | _MetaItem_
 > &nbsp;&nbsp; | _MetaItem_ `,` _MetaSeq_
 
 Any [item declaration] or [generic lifetime or type parameter][generics] may
@@ -116,7 +116,7 @@ On an `extern` block, the following attributes are interpreted:
   declarations in this block to be linked correctly. `link` supports an optional
   `kind` key with three possible values: `dylib`, `static`, and `framework`. See
   [external blocks](items/external-blocks.html) for more about external blocks.
-  Two examples: `#[link(name = "readline")]` and 
+  Two examples: `#[link(name = "readline")]` and
   `#[link(name = "CoreFoundation", kind = "framework")]`.
 - `linked_from` - indicates what native library this block of FFI items is
   coming from. This attribute is of the form `#[linked_from = "foo"]` where
@@ -165,6 +165,8 @@ information on macro scope.
   object file that this item's contents will be placed into.
 - `no_mangle` - on any item, do not apply the standard name mangling. Set the
   symbol for this item to its identifier.
+- `used` - on statics, this forces the compiler to keep the variable in the
+  output object file.
 
 ### Deprecation
 
@@ -450,7 +452,7 @@ When used on a function in an implementation, the attribute does nothing.
 >   { five() };
 >   if true { five() } else { 0i32 };
 >   match true {
->     _ => five()  
+>     _ => five()
 >   };
 > }
 > ```