address review comments

Author: japaric

src/SUMMARY.md

@@ -112,7 +112,6 @@
 - [Constant Evaluation](const_eval.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

@@ -204,6 +204,8 @@ which can be used to control type layout.
   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