Merge pull request #537 from ehuss/attribute-reorg-syntax

Reorg and update attributes

Author: Centril

src/SUMMARY.md

@@ -21,25 +21,30 @@
 
 - [Conditional compilation](conditional-compilation.md)
 
-- [Items and attributes](items-and-attributes.md)
-    - [Items](items.md)
-        - [Modules](items/modules.md)
-        - [Extern crates](items/extern-crates.md)
-        - [Use declarations](items/use-declarations.md)
-        - [Functions](items/functions.md)
-        - [Type aliases](items/type-aliases.md)
-        - [Structs](items/structs.md)
-        - [Enumerations](items/enumerations.md)
-        - [Unions](items/unions.md)
-        - [Constant items](items/constant-items.md)
-        - [Static items](items/static-items.md)
-        - [Traits](items/traits.md)
-        - [Implementations](items/implementations.md)
-        - [External blocks](items/external-blocks.md)
+- [Items](items.md)
+    - [Modules](items/modules.md)
+    - [Extern crates](items/extern-crates.md)
+    - [Use declarations](items/use-declarations.md)
+    - [Functions](items/functions.md)
+    - [Type aliases](items/type-aliases.md)
+    - [Structs](items/structs.md)
+    - [Enumerations](items/enumerations.md)
+    - [Unions](items/unions.md)
+    - [Constant items](items/constant-items.md)
+    - [Static items](items/static-items.md)
+    - [Traits](items/traits.md)
+    - [Implementations](items/implementations.md)
+    - [External blocks](items/external-blocks.md)
     - [Type and lifetime parameters](items/generics.md)
     - [Associated Items](items/associated-items.md)
     - [Visibility and Privacy](visibility-and-privacy.md)
-    - [Attributes](attributes.md)
+
+- [Attributes](attributes.md)
+    - [Testing](attributes/testing.md)
+    - [Derive](attributes/derive.md)
+    - [Diagnostics](attributes/diagnostics.md)
+    - [Code generation](attributes/codegen.md)
+    - [Limits](attributes/limits.md)
 
 - [Statements and expressions](statements-and-expressions.md)
     - [Statements](statements.md)

src/abi.md

@@ -56,7 +56,40 @@ $ nm -C foo.o
 0000000000000000 T foo::quux
 ```
 
+## The `no_mangle` attribute
+
+The *`no_mangle` attribute* may be used on any [item] to disable standard
+symbol name mangling. The symbol for the item will be the identifier of the
+item's name.
+
+## The `link_section` attribute
+
+The *`link_section` attribute* specifies the section of the object file that a
+[function] or [static]'s content will be placed into. It uses the
+[_MetaNameValueStr_] syntax to specify the section name.
+
+```rust,ignore
+#[no_mangle]
+#[link_section = ".example_section"]
+pub static VAR1: u32 = 1;
+```
+
+## The `export_name` attribute
+
+The *`export_name` attribute* specifies the name of the symbol that will be
+exported on a [function] or [static]. It uses the [_MetaNameValueStr_] syntax
+to specify the symbol name.
+
+```rust,ignore
+#[export_name = "exported_symbol_name"]
+pub fn name_in_rust() { }
+```
+
+[_MetaNameValueStr_]: attributes.html#meta-item-attribute-syntax
 [`static` items]: items/static-items.html
 [attribute]: attributes.html
 [extern functions]: items/functions.html#extern-functions
 [external blocks]: items/external-blocks.html
+[function]: items/functions.html
+[item]: items.html
+[static]: items/static-items.html

src/attributes-redirect.html

@@ -0,0 +1,29 @@
+<script>
+(function() {
+    var fragments = {
+        "#cold-attribute": "codegen.html#the-cold-attribute",
+        "#conditional-compilation": "conditional-compilation.html",
+        "#deprecation": "diagnostics.html#the-deprecated-attribute",
+        "#derive": "attributes/derive.html",
+        "#documentation": "../rustdoc/the-doc-attribute.html",
+        "#ffi-attributes": "attributes.html#built-in-attributes-index",
+        "#inline-attribute": "codegen.html#the-inline-attribute",
+        "#lint-check-attributes": "diagnostics.html#lint-check-attributes",
+        "#macro-related-attributes": "attributes.html#built-in-attributes-index",
+        "#miscellaneous-attributes": "attributes.html#built-in-attributes-index",
+        "#must_use": "diagnostics.html#the-must_use-attribute",
+        "#optimization-hints": "codegen.html#optimization-hints",
+        "#path": "items/modules.html#the-path-attribute",
+        "#preludes": "crates-and-source-files.html#preludes-and-no_std",
+        "#testing": "testing.html",
+        "#tool-lint-attributes": "diagnostics.html#tool-lint-attributes",
+        "#crate-only-attributes": "attributes.html#built-in-attributes-index",
+    };
+    var target = fragments[window.location.hash];
+    if (target) {
+        var url = window.location.toString();
+        var base = url.substring(0, url.lastIndexOf('/'));
+        window.location.replace(base + "/" + target);
+    }
+})();
+</script>

src/attributes.md

@@ -0,0 +1,48 @@
+# Code generation attributes
+
+The following [attributes] are used for controlling code generation.
+
+## Optimization hints
+
+The `cold` and `inline` [attributes] give suggestions to generate code in a
+way that may be faster than what it would do without the hint. The attributes
+are only hints, and may be ignored.
+
+Both attributes can be used on [functions]. When applied to a function in a
+[trait], they apply only to that function when used as a default function for
+a trait implementation and not to all trait implementations. The attributes
+have no effect on a trait function without a body.
+
+### The `inline` attribute
+
+The *`inline` [attribute]* suggests that a copy of the attributed function
+should be placed in the caller, rather than generating code to call the
+function where it is defined.
+
+> ***Note***: The `rustc` compiler automatically inlines functions based on
+> internal heuristics. Incorrectly inlining functions can make the program
+> slower, so this attribute should be used with care.
+
+There are three ways to use the inline attribute:
+
+* `#[inline]` suggests performing an inline expansion.
+* `#[inline(always)]` suggests that an inline expansion should always be
+  performed.
+* `#[inline(never)]` suggests that an inline expansion should never be
+  performed.
+
+### The `cold` attribute
+
+The *`cold` [attribute]* suggests that the attributed function is unlikely to
+be called.
+
+## The `no_builtins` attribute
+
+The *`no_builtins` [attribute]* may be applied at the crate level to disable
+optimizing certain code patterns to invocations of library functions that are
+assumed to exist.
+
+[attribute]: attributes.html
+[attributes]: attributes.html
+[functions]: items/functions.html
+[trait]: items/traits.html

src/attributes/codegen.md

@@ -0,0 +1,42 @@
+# Derive
+
+The *`derive` attribute* allows new [items] to be automatically generated for
+data structures. It uses the [_MetaListPaths_] syntax to specify a list of
+traits to implement or paths to [derive macros] to process.
+
+For example, the following will create an [`impl` item] for the
+[`PartialEq`] and [`Clone`] traits for `Foo`, and the type parameter `T` will be
+given the `PartialEq` or `Clone` constraints for the appropriate `impl`:
+
+```rust
+#[derive(PartialEq, Clone)]
+struct Foo<T> {
+    a: i32,
+    b: T,
+}
+```
+
+The generated `impl` for `PartialEq` is equivalent to
+
+```rust
+# struct Foo<T> { a: i32, b: T }
+impl<T: PartialEq> PartialEq for Foo<T> {
+    fn eq(&self, other: &Foo<T>) -> bool {
+        self.a == other.a && self.b == other.b
+    }
+
+    fn ne(&self, other: &Foo<T>) -> bool {
+        self.a != other.a || self.b != other.b
+    }
+}
+```
+
+You can implement `derive` for your own traits through [procedural macros].
+
+[_MetaListPaths_]: attributes.html#meta-item-attribute-syntax
+[`Clone`]: ../std/clone/trait.Clone.html
+[`PartialEq`]: ../std/cmp/trait.PartialEq.html
+[`impl` item]: items/implementations.html
+[items]: items.html
+[derive macros]: procedural-macros.html#derive-macros
+[procedural macros]: procedural-macros.html#derive-macros

src/attributes/derive.md

@@ -0,0 +1,281 @@
+# Diagnostic attributes
+
+The following [attributes] are used for controlling or generating diagnostic
+messages during compilation.
+
+## Lint check attributes
+
+A lint check names a potentially undesirable coding pattern, such as
+unreachable code or omitted documentation. The lint attributes `allow`,
+`warn`, `deny`, and `forbid` use the [_MetaListPaths_] syntax to specify a
+list of lint names to change the lint level for the entity to which the
+attribute applies.
+
+For any lint check `C`:
+
+* `allow(C)` overrides the check for `C` so that violations will go
+   unreported,
+* `warn(C)` warns about violations of `C` but continues compilation.
+* `deny(C)` signals an error after encountering a violation of `C`,
+* `forbid(C)` is the same as `deny(C)`, but also forbids changing the lint
+   level afterwards,
+
+> Note: The lint checks supported by `rustc` can be found via `rustc -W help`,
+> along with their default settings and are documented in the [rustc book].
+
+```rust
+pub mod m1 {
+    // Missing documentation is ignored here
+    #[allow(missing_docs)]
+    pub fn undocumented_one() -> i32 { 1 }
+
+    // Missing documentation signals a warning here
+    #[warn(missing_docs)]
+    pub fn undocumented_too() -> i32 { 2 }
+
+    // Missing documentation signals an error here
+    #[deny(missing_docs)]
+    pub fn undocumented_end() -> i32 { 3 }
+}
+```
+
+This example shows how one can use `allow` and `warn` to toggle a particular
+check on and off:
+
+```rust
+#[warn(missing_docs)]
+pub mod m2{
+    #[allow(missing_docs)]
+    pub mod nested {
+        // Missing documentation is ignored here
+        pub fn undocumented_one() -> i32 { 1 }
+
+        // Missing documentation signals a warning here,
+        // despite the allow above.
+        #[warn(missing_docs)]
+        pub fn undocumented_two() -> i32 { 2 }
+    }
+
+    // Missing documentation signals a warning here
+    pub fn undocumented_too() -> i32 { 3 }
+}
+```
+
+This example shows how one can use `forbid` to disallow uses of `allow` for
+that lint check:
+
+```rust,compile_fail
+#[forbid(missing_docs)]
+pub mod m3 {
+    // Attempting to toggle warning signals an error here
+    #[allow(missing_docs)]
+    /// Returns 2.
+    pub fn undocumented_too() -> i32 { 2 }
+}
+```
+
+### Tool lint attributes
+
+Tool lints allows using scoped lints, to `allow`, `warn`, `deny` or `forbid`
+lints of certain tools.
+
+Currently `clippy` is the only available lint tool.
+
+Tool lints only get checked when the associated tool is active. If a lint
+attribute, such as `allow`, references a nonexistent tool lint, the compiler
+will not warn about the nonexistent lint until you use the tool.
+
+Otherwise, they work just like regular lint attributes:
+
+```rust
+// set the entire `pedantic` clippy lint group to warn
+#![warn(clippy::pedantic)]
+// silence warnings from the `filter_map` clippy lint
+#![allow(clippy::filter_map)]
+
+fn main() {
+    // ...
+}
+
+// silence the `cmp_nan` clippy lint just for this function
+#[allow(clippy::cmp_nan)]
+fn foo() {
+    // ...
+}
+```
+
+## The `deprecated` attribute
+
+The *`deprecated` attribute* marks an item as deprecated. `rustc` will issue
+warnings on usage of `#[deprecated]` items. `rustdoc` will show item
+deprecation, including the `since` version and `note`, if available.
+
+The `deprecated` attribute has several forms:
+
+- `deprecated` — Issues a generic message.
+- `deprecated = "message"` — Includes the given string in the deprecation
+  message.
+- [_MetaListNameValueStr_] syntax with two optional fields:
+  - `since` — Specifies a version number when the item was deprecated. `rustc`
+    does not currently interpret the string, but external tools like [Clippy]
+    may check the validity of the value.
+  - `note` — Specifies a string that should be included in the deprecation
+    message. This is typically used to provide an explanation about the
+    deprecation and preferred alternatives.
+
+The `deprecated` attribute may be applied to any [item], [trait item], [enum
+variant], [struct field], or [external block item]. It cannot be applied to [trait
+implementation items]. When applied to an item containing other items, such as
+a [module] or [implementation], all child items inherit the deprecation attribute.
+<!-- NOTE: Currently broken for macros, see https://github.com/rust-lang/rust/issues/49912
+Also, it is only rejected for trait impl items (AnnotationKind::Prohibited). In all
+other locations, it is silently ignored. Tuple struct fields are ignored.
+-->
+
+Here is an example:
+
+```rust
+#[deprecated(since = "5.2", note = "foo was rarely used. Users should instead use bar")]
+pub fn foo() {}
+
+pub fn bar() {}
+```
+
+The [RFC][1270-deprecation.md] contains motivations and more details.
+
+[1270-deprecation.md]: https://github.com/rust-lang/rfcs/blob/master/text/1270-deprecation.md
+
+## The `must_use` attribute
+
+The *`must_use` attribute* is used to issue a diagnostic warning when a value
+is not "used". It can be applied to user-defined composite types
+([`struct`s][struct], [`enum`s][enum], and [`union`s][union]), [functions],
+and [traits].
+
+The `must_use` attribute may include a message by using the
+[_MetaNameValueStr_] syntax such as `#[must_use = "example message"]`. The
+message will be given alongside the warning.
+
+When used on user-defined composite types, if the [expression] of an
+[expression statement] has that type, then the `unused_must_use` lint is
+violated.
+
+```rust
+#[must_use]
+struct MustUse {
+    // some fields
+}
+
+# impl MustUse {
+#   fn new() -> MustUse { MustUse {} }
+# }
+#
+// Violates the `unused_must_use` lint.
+MustUse::new();
+```
+
+When used on a function, if the [expression] of an [expression statement] is a
+[call expression] to that function, then the `unused_must_use` lint is
+violated.
+
+```rust
+#[must_use]
+fn five() -> i32 { 5i32 }
+
+// Violates the unused_must_use lint.
+five();
+```
+
+When used on a [trait declaration], a [call expression] of an [expression
+statement] to a function that returns an [impl trait] of that trait violates
+the `unsued_must_use` lint.
+
+```rust
+#[must_use]
+trait Critical {}
+impl Critical for i32 {}
+
+fn get_critical() -> impl Critical {
+    4i32
+}
+
+// Violates the `unused_must_use` lint.
+get_critical();
+```
+
+When used on a function in a trait declaration, then the behavior also applies
+when the call expression is a function from an implementation of the trait.
+
+```rust
+trait Trait {
+    #[must_use]
+    fn use_me(&self) -> i32;
+}
+
+impl Trait for i32 {
+    fn use_me(&self) -> i32 { 0i32 }
+}
+
+// Violates the `unused_must_use` lint.
+5i32.use_me();
+```
+
+When used on a function in a trait implementation, the attribute does nothing.
+
+> Note: Trivial no-op expressions containing the value will not violate the
+> lint. Examples include wrapping the value in a type that does not implement
+> [`Drop`] and then not using that type and being the final expression of a
+> [block expression] that is not used.
+>
+> ```rust
+> #[must_use]
+> fn five() -> i32 { 5i32 }
+>
+> // None of these violate the unused_must_use lint.
+> (five(),);
+> Some(five());
+> { five() };
+> if true { five() } else { 0i32 };
+> match true {
+>     _ => five()
+> };
+> ```
+
+> Note: It is idiomatic to use a [let statement] with a pattern of `_`
+> when a must-used value is purposely discarded.
+>
+> ```rust
+> #[must_use]
+> fn five() -> i32 { 5i32 }
+>
+> // Does not violate the unused_must_use lint.
+> let _ = five();
+> ```
+
+[Clippy]: https://github.com/rust-lang/rust-clippy
+[_MetaListNameValueStr_]: attributes.html#meta-item-attribute-syntax
+[_MetaListPaths_]: attributes.html#meta-item-attribute-syntax
+[_MetaNameValueStr_]: attributes.html#meta-item-attribute-syntax
+[`Drop`]: special-types-and-traits.html#drop
+[attributes]: attributes.html
+[block expression]: expressions/block-expr.html
+[call expression]: expressions/call-expr.html
+[enum variant]: items/enumerations.html
+[enum]: items/enumerations.html
+[expression statement]: statements.html#expression-statements
+[expression]: expressions.html
+[external block item]: items/external-blocks.html
+[functions]: items/functions.html
+[impl trait]: types/impl-trait.html
+[implementation]: items/implementations.html
+[item]: items.html
+[let statement]: statements.html#let-statements
+[module]: items/modules.html
+[rustc book]: ../rustc/lints/index.html
+[struct field]: items/structs.html
+[struct]: items/structs.html
+[trait declaration]: items/traits.html
+[trait implementation items]: items/implementations.html#trait-implementations
+[trait item]: items/traits.html
+[traits]: items/traits.html
+[union]: items/unions.html

src/attributes/diagnostics.md

@@ -0,0 +1,14 @@
+# Limits
+
+The following [attributes] affect compile-time limits.
+
+## The `recursion_limit` attribute
+
+The *`recursion_limit` attribute* may be applied at the crate level to set the
+maximum depth for potentially infinitely-recursive compile-time operations
+like auto-dereference or macro expansion. It uses the [_MetaNameValueStr_]
+syntax to specify the recursion depth. The default is
+`#![recursion_limit="64"]`.
+
+[attributes]: attributes.html
+[_MetaNameValueStr_]: attributes.html#meta-item-attribute-syntax

src/attributes/limits.md

@@ -0,0 +1,91 @@
+# Testing attributes
+
+The following [attributes] are used for specifying functions for performing
+tests. Compiling a crate in "test" mode enables building the test functions
+along with a test harness for executing the tests. Enabling the test mode also
+enables the [`test` conditional compilation option].
+
+## The `test` attribute
+
+The *`test` attribute* marks a function to be executed as a test. These
+functions are only compiled when in test mode. Test functions must be free,
+monomorphic functions that take no arguments, and the return type must be one
+of the following:
+
+* `()`
+* `Result<(), E> where E: Error`
+<!-- * `!` -->
+<!-- * Result<!, E> where E: Error` -->
+
+> Note: The implementation of which return types are allowed is determined by
+> the unstable [`Termination`] trait.
+
+<!-- If the previous section needs updating (from "must take no arguments"
+  onwards, also update it in the crates-and-source-files.md file -->
+
+> Note: The test mode is enabled by passing the `--test` argument to `rustc`
+> or using `cargo test`.
+
+Tests that return `()` pass as long as they terminate and do not panic. Tests
+that return a `Result<(), E>` pass as long as they return `Ok(())`. Tests that
+do not terminate neither pass nor fail.
+
+```rust
+# use std::io;
+# fn setup_the_thing() -> io::Result<i32> { Ok(1) }
+# fn do_the_thing(s: &i32) -> io::Result<()> { Ok(()) }
+#[test]
+fn test_the_thing() -> io::Result<()> {
+    let state = setup_the_thing()?; // expected to succeed
+    do_the_thing(&state)?;          // expected to succeed
+    Ok(())
+}
+```
+
+## The `ignore` attribute
+
+A function annotated with the `test` attribute can also be annotated with the
+`ignore` attribute. The *`ignore` attribute* tells the test harness to not
+execute that function as a test. It will still be compiled when in test mode.
+
+The `ignore` attribute may optionally be written with the [_MetaNameValueStr_]
+syntax to specify a reason why the test is ignored.
+
+```rust
+#[test]
+#[ignore = "not yet implemented"]
+fn mytest() {
+    // …
+}
+```
+
+> **Note**: The `rustc` test harness supports the `--include-ignored` flag to
+> force ignored tests to be run.
+
+## The `should_panic` attribute
+
+A function annotated with the `test` attribute that returns `()` can also be
+annotated with the `should_panic` attribute. The *`should_panic` attribute*
+makes the test only pass if it actually panics.
+
+The `should_panic` attribute may optionally take an input string that must
+appear within the panic message. If the string is not found in the message,
+then the test will fail. The string may be passed using the
+[_MetaNameValueStr_] syntax or the [_MetaListNameValueStr_] syntax with an
+`expected` field.
+
+```rust
+#[test]
+#[should_panic(expected = "values don't match")]
+fn mytest() {
+    assert_eq!(1, 2, "values don't match");
+}
+```
+
+[_MetaListNameValueStr_]: attributes.html#meta-item-attribute-syntax
+[_MetaNameValueStr_]: attributes.html#meta-item-attribute-syntax
+[`Termination`]: ../std/process/trait.Termination.html
+[`test` conditional compilation option]: conditional-compilation.html#test
+[attributes]: attributes.html
+[trait or lifetime bounds]: trait-bounds.html
+[where clauses]: items/generics.html#where-clauses

src/attributes/testing.md

@@ -43,7 +43,7 @@ Non-doc comments are interpreted as a form of whitespace.
 
 Line doc comments beginning with exactly _three_ slashes (`///`), and block
 doc comments (`/** ... */`), both inner doc comments, are interpreted as a
-special syntax for `doc` [attributes]. That is, they are equivalent to writing
+special syntax for [`doc` attributes]. That is, they are equivalent to writing
 `#[doc="..."]` around the body of the comment, i.e., `/// Foo` turns into
 `#[doc="Foo"]` and `/** Bar */` turns into `#[doc="Bar"]`.
 
@@ -122,4 +122,4 @@ pub mod outer_module {
 }
 ```
 
-[attributes]: attributes.html
+[`doc` attributes]: ../rustdoc/the-doc-attribute.html

src/comments.md

@@ -167,7 +167,7 @@ Example values:
 ### `test`
 
 Enabled when compiling the test harness. Done with `rustc` by using the
-[`--test`] flag.
+[`--test`] flag. See [Testing] for more on testing support.
 
 ### `debug_assertions`
 
@@ -297,6 +297,7 @@ println!("I'm running on a {} machine!", machine_kind);
 [IDENTIFIER]: identifiers.html
 [RAW_STRING_LITERAL]: tokens.html#raw-string-literals
 [STRING_LITERAL]: tokens.html#string-literals
+[Testing]: attributes/testing.html
 [_Attr_]: attributes.html
 [`--cfg`]: ../rustc/command-line-arguments.html#a--cfg-configure-the-compilation-environment
 [`--test`]: ../rustc/command-line-arguments.html#a--test-build-a-test-harness
@@ -307,5 +308,3 @@ println!("I'm running on a {} machine!", machine_kind);
 [attribute]: attributes.html
 [attributes]: attributes.html
 [crate type]: linkage.html
-[expressions]: expressions.html
-[items]: items.html

src/conditional-compilation.md

@@ -123,7 +123,25 @@ type must  be one of the following:
 > the unstable [`Termination`] trait.
 
 <!-- If the previous section needs updating (from "must take no arguments"
-  onwards, also update it in the attributes.md file, testing section -->
+  onwards, also update it in the testing.md file -->
+
+### The `no_main` attribute
+
+The *`no_main` [attribute]* may be applied at the crate level to disable
+emitting the `main` symbol for an executable binary. This is useful when some
+other object being linked to defines `main`.
+
+## The `crate_name` attribute
+
+The *`crate_name` [attribute]* may be applied at the crate level to specify the
+name of the crate with the [_MetaNameValueStr_] syntax.
+
+```rust,ignore
+#![crate_name = "mycrate"]
+```
+
+The crate name must not be empty, and must only contain [Unicode alphanumeric]
+or `-` (U+002D) characters.
 
 [^phase-distinction]: This distinction would also exist in an interpreter.
     Static checks like syntactic analysis, type checking, and lints should
@@ -133,8 +151,10 @@ type must  be one of the following:
     ECMA-335 CLI model, a *library* in the SML/NJ Compilation Manager, a *unit*
     in the Owens and Flatt module system, or a *configuration* in Mesa.
 
+[Unicode alphanumeric]: ../std/primitive.char.html#method.is_alphanumeric
 [_InnerAttribute_]: attributes.html
 [_Item_]: items.html
+[_MetaNameValueStr_]: attributes.html#meta-item-attribute-syntax
 [_shebang_]: https://en.wikipedia.org/wiki/Shebang_(Unix)
 [_utf8 byte order mark_]: https://en.wikipedia.org/wiki/Byte_order_mark#UTF-8
 [`Termination`]: ../std/process/trait.Termination.html

src/crates-and-source-files.md

@@ -148,7 +148,7 @@ fn is_unix_platform() -> bool {
 [statement]: statements.html
 [statements]: statements.html
 [struct]: expressions/struct-expr.html
-[the lint check attributes]: attributes.html#lint-check-attributes
+[the lint check attributes]: attributes/diagnostics.html#lint-check-attributes
 [tuple expressions]: expressions/tuple-expr.html
 [unsafe operations]: unsafety.html
 [value expressions]: expressions.html#place-expressions-and-value-expressions

src/expressions/block-expr.md

@@ -128,7 +128,7 @@ 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].
+meaning on match arms are [`cfg`], [`cold`], and the [lint check attributes].
 
 [Inner attributes] are allowed directly after the opening brace of the match
 expression in the same expression contexts as [attributes on block
@@ -141,7 +141,8 @@ expressions].
 [_InnerAttribute_]: attributes.html
 [_OuterAttribute_]: attributes.html
 [`cfg`]: conditional-compilation.html
-[lint check attributes]: attributes.html#lint-check-attributes
+[`cold`]: attributes/codegen.html#the-cold-attribute
+[lint check attributes]: attributes/diagnostics.html#lint-check-attributes
 [Range Expression]: expressions/range-expr.html
 
 [_Pattern_]: patterns.html

src/expressions/match-expr.md

@@ -93,12 +93,18 @@ by using an underscore with the form `extern crate foo as _`. This may be
 useful for crates that only need to be linked, but are never referenced, and
 will avoid being reported as unused.
 
-The [`#[macro_use]` attribute] will work as usual and import the macro names
+The [`macro_use` attribute] works as usual and import the macro names
 into the macro-use prelude.
 
+## The `no_link` attribute
+
+The *`no_link` attribute* may be specified on an `extern crate` item to
+prevent linking the crate into the output. This is commonly used to load a
+crate to access only its macros.
+
 [IDENTIFIER]: identifiers.html
 [RFC 940]: https://github.com/rust-lang/rfcs/blob/master/text/0940-hyphens-considered-harmful.md
-[`#[macro_use]` attribute]: macros-by-example.html#the-macro_use-attribute
+[`macro_use` attribute]: macros-by-example.html#the-macro_use-attribute
 [`alloc`]: https://doc.rust-lang.org/alloc/
 [`crate::`]: paths.html#crate
 [`no_implicit_prelude`]: items/modules.html#prelude-items

src/items-and-attributes.md

@@ -42,16 +42,16 @@ Functions within external blocks may be called by Rust code, just like
 functions defined in Rust. The Rust compiler automatically translates between
 the Rust ABI and the foreign ABI.
 
-Functions within external blocks may be variadic by specifying `...` after one
-or more named arguments in the argument list:
+A function declared in an extern block is implicitly `unsafe`. When coerced to
+a function pointer, a function declared in an extern block has type `unsafe
+extern "abi" for<'l1, ..., 'lm> fn(A1, ..., An) -> R`, where `'l1`, ... `'lm`
+are its lifetime parameters, `A1`, ..., `An` are the declared types of its
+parameters and `R` is the declared return type.
 
-```rust,ignore
-extern {
-    fn foo(x: i32, ...);
-}
-```
+It is `unsafe` to access a static item declared in an extern block, whether or
+not it's mutable.
 
-A number of [attributes] control the behavior of external blocks.
+## ABI
 
 By default external blocks assume that the library they are calling uses the
 standard C ABI on the specific platform. Other ABIs may be specified using an
@@ -92,38 +92,76 @@ Finally, there are some rustc-specific ABI strings:
 * `extern "platform-intrinsic"` -- Specific platform intrinsics -- like, for
   example, `sqrt` -- have this ABI. You should never have to deal with it.
 
-The `link` attribute allows the name of the library to be specified. When
-specified the compiler will attempt to link against the native library of the
-specified name.
+## Variadic functions
+
+Functions within external blocks may be variadic by specifying `...` after one
+or more named arguments in the argument list:
 
 ```rust,ignore
-#[link(name = "crypto")]
-extern { }
+extern {
+    fn foo(x: i32, ...);
+}
 ```
 
-A function declared in an extern block is implicitly `unsafe`. When coerced to
-a function pointer, a function declared in an extern block has type `unsafe
-extern "abi" for<'l1, ..., 'lm> fn(A1, ..., An) -> R`, where `'l1`, ... `'lm`
-are its lifetime parameters, `A1`, ..., `An` are the declared types of its
-parameters and `R` is the declared return type.
+## Attributes on extern blocks
 
-It is `unsafe` to access a static item declared in an extern block, whether or
-not it's mutable.
+The following [attributes] control the behavior of external blocks.
+
+### The `link` attribute
+
+The *`link` attribute* specifies the name of a native library that the
+compiler should link with. It uses the [_MetaListNameValueStr_] syntax to
+specify its inputs. The `name` key is the name of the native library to link.
+The `kind` key is an optional value which specifies the kind of library with
+the following possible values:
+
+- `dylib` — Indicates a dynamic library. This is the default if `kind` is not
+  specified.
+- `static` — Indicates a static library.
+- `framework` — Indicates a macOS framework. This is only valid for macOS
+  targets.
+
+```rust,ignore
+#[link(name = "crypto")]
+extern {
+    // …
+}
+
+#[link(name = "CoreFoundation", kind = "framework")]
+extern {
+    // …
+}
+```
 
 It is valid to add the `link` attribute on an empty extern block. You can use
 this to satisfy the linking requirements of extern blocks elsewhere in your
 code (including upstream crates) instead of adding the attribute to each extern
 block.
 
+### The `link_name` attribute
+
+The `link_name` attribute may be specified on declarations inside an `extern`
+block to indicate the symbol to import for the given function or static. It
+uses the [_MetaNameValueStr_] syntax to specify the name of the symbol.
+
+```rust,ignore
+extern {
+    #[link_name = "actual_symbol_name"]
+    fn name_in_rust();
+}
+```
+
 [IDENTIFIER]: identifiers.html
 [_Abi_]: items/functions.html
 [_FunctionParam_]: items/functions.html
 [_FunctionParameters_]: items/functions.html
 [_FunctionReturnType_]: items/functions.html
 [_Generics_]: items/generics.html
 [_InnerAttribute_]: attributes.html
+[_MetaListNameValueStr_]: attributes.html#meta-item-attribute-syntax
+[_MetaNameValueStr_]: attributes.html#meta-item-attribute-syntax
 [_OuterAttribute_]: attributes.html
 [_Type_]: types.html#type-expressions
 [_Visibility_]: visibility-and-privacy.html
 [_WhereClause_]: items/generics.html#where-clauses
-[attributes]: attributes.html#ffi-attributes
+[attributes]: attributes.html

src/items/extern-crates.md

@@ -207,7 +207,7 @@ fn test_only() {
 > function items.
 
 The attributes that have meaning on a function are [`cfg`], [`deprecated`],
-[`doc`], `export_name`, `link_section`, `no_mangle`, [the lint check
+[`doc`], [`export_name`], [`link_section`], [`no_mangle`], [the lint check
 attributes], [`must_use`], [the procedural macro attributes], [the testing
 attributes], and [the optimization hint attributes]. Functions also accept
 attributes macros.
@@ -232,13 +232,16 @@ attributes macros.
 [Trait]: items/traits.html
 [attributes]: attributes.html
 [`cfg`]: conditional-compilation.html
-[the lint check attributes]: attributes.html#lint-check-attributes
+[the lint check attributes]: attributes/diagnostics.html#lint-check-attributes
 [the procedural macro attributes]: procedural-macros.html
-[the testing attributes]: attributes.html#testing
-[the optimization hint attributes]: attributes.html#optimization-hints
-[`deprecated`]: attributes.html#deprecation
-[`doc`]: attributes.html#documentation
-[`must_use`]: attributes.html#must_use
+[the testing attributes]: attributes/testing.html
+[the optimization hint attributes]: attributes/codegen.html#optimization-hints
+[`deprecated`]: attributes/diagnostics.html#the-deprecated-attribute
+[`doc`]: ../rustdoc/the-doc-attribute.html
+[`must_use`]: attributes/diagnostics.html#the-must_use-attribute
 [patterns]: patterns.html
 [`?Sized`]: trait-bounds.html#sized
 [trait bounds]: trait-bounds.html
+[`export_name`]: abi.html#the-export_name-attribute
+[`link_section`]: abi.html#the-link_section-attribute
+[`no_mangle`]: abi.html#the-no_mangle-attribute

src/items/external-blocks.md

@@ -220,8 +220,8 @@ attributes].
 [associated constants]: items/associated-items.html#associated-constants
 [attributes]: attributes.html
 [`cfg`]: conditional-compilation.html
-[`deprecated`]: attributes.html#deprecation
-[`doc`]: attributes.html#documentation
+[`deprecated`]: attributes/diagnostics.html#the-deprecated-attribute
+[`doc`]: ../rustdoc/the-doc-attribute.html
 [path]: paths.html
-[the lint check attributes]: attributes.html#lint-check-attributes
+[the lint check attributes]: attributes/diagnostics.html#lint-check-attributes
 [Unsafe traits]: items/traits.html#unsafe-traits

src/items/functions.md

@@ -65,7 +65,7 @@ alternately be expressed with `crate::util`'s contents in a file named
 > convention as it is more consistent, and avoids having many files named
 > `mod.rs` within a project.
 
-### `path` Attribute
+### The `path` attribute
 
 The directories and files used for loading external file modules can be
 influenced with the `path` attribute.
@@ -144,11 +144,11 @@ The built-in attributes that have meaning on a function are [`cfg`],
 [_OuterAttribute_]: attributes.html
 [`#[macro_use]`]: macros-by-example.html#the-macro_use-attribute
 [`cfg`]: conditional-compilation.html
-[`deprecated`]: attributes.html#deprecation
-[`doc`]: attributes.html#documentation
+[`deprecated`]: attributes/diagnostics.html#the-deprecated-attribute
+[`doc`]: ../rustdoc/the-doc-attribute.html
 [IDENTIFIER]: identifiers.html
 [attribute]: attributes.html
 [items]: items.html
 [module path]: paths.html
 [prelude]: crates-and-source-files.html#preludes-and-no_std
-[the lint check attributes]: attributes.html#lint-check-attributes
+[the lint check attributes]: attributes/diagnostics.html#lint-check-attributes

src/items/implementations.md

@@ -307,8 +307,8 @@ imported this way are imported into the prelude of the crate, not textually,
 which means that they can be shadowed by any other name. While macros imported
 by `#[macro_use]` can be used before the import statement, in case of a
 conflict, the last macro imported wins. Optionally, a list of macros to import
-can be specified; this is not supported when `#[macro_use]` is applied to a
-module.
+can be specified using the [_MetaListIdents_] syntax; this is not supported
+when `#[macro_use]` is applied to a module.
 
 ```rust,ignore
 #[macro_use(lazy_static)] // Or #[macro_use] to import all macros.
@@ -487,6 +487,7 @@ For more detail, see the [formal specification].
 [_Item_]: items.html
 [_LiteralExpression_]: expressions/literal-expr.html
 [_MetaItem_]: attributes.html#meta-item-attribute-syntax
+[_MetaListIdents_]: attributes.html#meta-item-attribute-syntax
 [_Pattern_]: patterns.html
 [_Statement_]: statements.html
 [_TokenTree_]: macros.html#macro-invocation

src/items/modules.md

@@ -113,7 +113,7 @@ as `make_answer!{}`, `make_answer!();` or `make_answer![];`.
 
 ### Derive macros
 
-*Derive macros* define new inputs for the `derive` [attribute]. These macros
+*Derive macros* define new inputs for the [`derive` attribute]. These macros
 can create new [items] given the token stream of a [struct], [enum], or [union].
 They can also define [derive macro helper attributes].
 
@@ -269,7 +269,7 @@ fn invoke4() {}
 [`TokenStream`]: ../proc_macro/struct.TokenStream.html
 [`TokenStream`s]: ../proc_macro/struct.TokenStream.html
 [`compile_error`]: ../std/macro.compile_error.html
-[`derive`]: attributes.html#derive
+[`derive` attribute]: attributes/derive.html
 [`proc_macro` crate]: ../proc_macro/index.html
 [Cargo's build scripts]: ../cargo/reference/build-scripts.html
 [Derive macros]: #derive-macros

src/macros-by-example.md

@@ -51,7 +51,29 @@ defaults to unwinding the stack but that can be [changed to abort the
 process][abort]. The standard library's panic behavior can be modified at
 runtime with the [set_hook] function.
 
+## The `global_allocator` attribute
+
+The *`global_allocator` attribute* is used on a [static item] implementing the
+[`GlobalAlloc`] trait to set the global allocator.
+
+## The `windows_subsystem` attribute
+
+The *`windows_subsystem` attribute* may be applied at the crate level to set
+the [subsystem] when linking on a Windows target. It uses the
+[_MetaNameValueStr_] syntax to specify the subsystem with a value of either
+`console` or `windows`. This attribute is ignored on non-Windows targets, and
+for non-`bin` [crate types].
+
+```rust,ignore
+#![windows_subsystem = "windows"]
+```
+
+[_MetaNameValueStr_]: attributes.html#meta-item-attribute-syntax
+[`GlobalAlloc`]: ../alloc/alloc/trait.GlobalAlloc.html
 [`PanicInfo`]: ../core/panic/struct.PanicInfo.html
 [abort]: ../book/ch09-01-unrecoverable-errors-with-panic.html
 [attribute]: attributes.html
+[crate types]: linkage.html
 [set_hook]: ../std/panic/fn.set_hook.html
+[static item]: items/static-items.html
+[subsystem]: https://msdn.microsoft.com/en-us/library/fcc1zstk.aspx

src/procedural-macros.md

@@ -125,7 +125,7 @@ statement are [`cfg`], and [the lint check attributes].
 [variables]: variables.html
 [outer attributes]: attributes.html
 [`cfg`]: conditional-compilation.html
-[the lint check attributes]: attributes.html#lint-check-attributes
+[the lint check attributes]: attributes/diagnostics.html#lint-check-attributes
 [pattern]: patterns.html
 [_ExpressionStatement_]: #expression-statements
 [_Expression_]: expressions.html

src/runtime.md

@@ -112,9 +112,9 @@ Closures have no layout guarantees.
 All user-defined composite types (`struct`s, `enum`s, and `union`s) have a
 *representation* that specifies what the layout is for the type.
 
-The possible representations for a type are the default representation, `C`, the
-primitive representations, and `packed`. Multiple representations can be applied
-to a single type.
+The possible representations for a type are the default representation, `C`,
+the primitive representations, `packed`, and `transparent`. Multiple
+representations can be applied to a single type.
 
 The representation of a type can be changed by applying the `repr` attribute
 to it. The following example shows a struct with a `C` representation.
@@ -258,8 +258,8 @@ layout is unspecified.
 ### Primitive representations
 
 The *primitive representations* are the representations with the same names as
-the primitive integer types. That is: `u8`, `u16`, `u32`, `u64`, `usize`, `i8`,
-`i16`, `i32`, `i64`, and `isize`.
+the primitive integer types. That is: `u8`, `u16`, `u32`, `u64`, `u128`,
+`usize`, `i8`, `i16`, `i32`, `i64`, `i128`, and `isize`.
 
 Primitive representations can only be applied to enumerations.
 

src/statements.md

@@ -174,4 +174,4 @@ Because captures are often by reference, the following general rules arise:
 [`Sized`]: special-types-and-traits.html#sized
 [`Sync`]: special-types-and-traits.html#sync
 [closure expression]: expressions/closure-expr.html
-[derived]: attributes.html#derive
+[derived]: attributes/derive.html

src/type-layout.md

@@ -7,7 +7,7 @@ New instances of a `struct` can be constructed with a [struct expression].
 
 The memory layout of a `struct` is undefined by default to allow for compiler
 optimizations like field reordering, but it can be fixed with the
-`#[repr(...)]` attribute. In either case, fields may be given in any order in a
+[`repr` attribute]. In either case, fields may be given in any order in a
 corresponding struct *expression*; the resulting `struct` value will always
 have the same memory layout.
 
@@ -24,5 +24,6 @@ value that inhabits such a type.
 [^structtype]: `struct` types are analogous to `struct` types in C, the
     *record* types of the ML family, or the *struct* types of the Lisp family.
 
+[`repr` attribute]: type-layout.html#representations
 [struct expression]: expressions/struct-expr.html
 [visibility modifiers]: visibility-and-privacy.html

src/types/closure.md

@@ -21,5 +21,5 @@ to shrink!
 [Flexible target specification]: https://github.com/rust-lang/rfcs/pull/131
 [Conditional compilation]: conditional-compilation.html
 [`dllimport`]: https://github.com/rust-lang/rfcs/pull/1717
-[FFI attributes]: attributes.html#ffi-attributes
+[FFI attributes]: attributes.html
 [define `crt_link`]: https://github.com/rust-lang/rfcs/pull/1721