Reorg and update attributes

src/SUMMARY.md

@@ -44,7 +44,7 @@
     - [Derive](attributes/derive.md)
     - [Diagnostics](attributes/diagnostics.md)
     - [Code generation](attributes/codegen.md)
-    - [Compiler settings](attributes/compiler-settings.md)
+    - [Limits](attributes/limits.md)
 
 - [Statements and expressions](statements-and-expressions.md)
     - [Statements](statements.md)

src/attributes.md

@@ -209,18 +209,13 @@ The following is an index of all built-in attributes.
   - [`link_section`] — Specifies the section of an object file to use for a
     function or static.
   - [`no_mangle`] — Disables symbol name encoding.
-  - [`used`] - Forces the compiler to keep a static variable in the output
+  - [`used`] — Forces the compiler to keep a static item in the output
     object file.
   - [`crate_name`] — Specifies the crate name.
 - Code generation
   - [`inline`] — Hint to inline code.
   - [`cold`] — Hint that a function is unlikely to be called.
   - [`no_builtins`] — Disables use of certain built-in functions.
-- Compiler setting attributes
-  - `feature` — Used to enable unstable or experimental compiler features. See
-    [The Unstable Book] for features implemented in `rustc`.
-  - [`recursion_limit`] — Sets the maximum recursion limit for certain
-    compile-time operations.
 - Documentation
   - `doc` — Specifies documentation. See [The Rustdoc Book] for more
     information. [Doc comments] are transformed into `doc` attributes.
@@ -229,10 +224,16 @@ The following is an index of all built-in attributes.
   - [`no_implicit_prelude`] — Disables prelude lookups within a module.
 - Modules
   - [`path`] — Specifies the filename for a module.
+- Limits
+  - [`recursion_limit`] — Sets the maximum recursion limit for certain
+    compile-time operations.
 - Runtime
   - [`panic_handler`] — Sets the function to handle panics.
   - [`global_allocator`] — Sets the global memory allocator.
   - [`windows_subsystem`] — Specifies the windows subsystem to link with.
+- Features
+  - `feature` — Used to enable unstable or experimental compiler features. See
+    [The Unstable Book] for features implemented in `rustc`.
 
 [Doc comments]: comments.html#doc-comments
 [ECMA-334]: https://www.ecma-international.org/publications/standards/Ecma-334.htm
@@ -278,7 +279,7 @@ The following is an index of all built-in attributes.
 [`proc_macro_attribute`]: procedural-macros.html#attribute-macros
 [`proc_macro_derive`]: procedural-macros.html#derive-macros
 [`proc_macro`]: procedural-macros.html#function-like-procedural-macros
-[`recursion_limit`]: attributes/compiler-settings.html#the-recursion_limit-attribute
+[`recursion_limit`]: attributes/limits.html#the-recursion_limit-attribute
 [`repr`]: type-layout.html#representations
 [`should_panic`]: attributes/testing.html#the-should_panic-attribute
 [`test`]: attributes/testing.html#the-test-attribute

src/attributes/codegen.md

@@ -4,10 +4,9 @@ The following [attributes] are used for controlling code generation.
 
 ## Optimization hints
 
-The `cold` and `inline` [attributes] give suggestions to the compiler to
-compile your code in a way that may be faster than what it would do without
-the hint. The attributes are only suggestions, and the compiler may choose to
-ignore it.
+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
@@ -16,24 +15,26 @@ have no effect on a trait function without a body.
 
 ### The `inline` attribute
 
-The *`inline` [attribute]* suggests to the compiler that it should place a
-copy of the attributed function in the caller, rather than generating code to
-call the function where it is defined.
+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 compiler automatically inlines functions based on internal
-> heuristics. Incorrectly inlining functions can actually make the program
+> ***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]` hints the compiler to perform an inline expansion.
-* `#[inline(always)]` asks the compiler to always perform an inline expansion.
-* `#[inline(never)]` asks the compiler to never perform an inline expansion.
+* `#[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 to the compiler that the attributed function
-is unlikely to be called.
+The *`cold` [attribute]* suggests that the attributed function is unlikely to
+be called.
 
 ## The `no_builtins` attribute
 

src/attributes/derive.md

@@ -1,11 +1,11 @@
 # Derive
 
-The *`derive` attribute* allows certain traits to be automatically implemented
-for data structures. It uses the [_MetaListPaths_] syntax to specify a list of
-traits to implement.
+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` for the
-`PartialEq` and `Clone` traits for `Foo`, and the type parameter `T` will be
+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
@@ -34,4 +34,9 @@ impl<T: PartialEq> PartialEq for Foo<T> {
 You can implement `derive` for your own traits through [procedural macros].
 
 [_MetaListPaths_]: attributes.html#meta-item-attribute-syntax
-[procedural macros]: procedural-macros.html
+[`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/diagnostics.md

@@ -15,14 +15,13 @@ 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,
-* `warn(C)` warns about violations of `C` but continues compilation.
 
-The lint checks supported by the compiler can be found via `rustc -W help`,
-along with their default settings and are documented in the [rustc book].
-[Compiler plugins] can provide additional lint checks.
+> 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 {
@@ -77,8 +76,8 @@ pub mod m3 {
 
 ### Tool lint attributes
 
-Tool lints let you use scoped lints, to `allow`, `warn`, `deny` or `forbid` lints of
-certain tools.
+Tool lints allows using scoped lints, to `allow`, `warn`, `deny` or `forbid`
+lints of certain tools.
 
 Currently `clippy` is the only available lint tool.
 
@@ -146,11 +145,11 @@ 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* can be used on user-defined composite types
-([`struct`s][struct], [`enum`s][enum], and [`union`s][union]) and [functions].
+([`struct`s][struct], [`enum`s][enum], and [`union`s][union]), [functions],
+and [traits].
 
 When used on user-defined composite types, if the [expression] of an
 [expression statement] has that type, then the `unused_must_use` lint is
@@ -159,32 +158,30 @@ violated.
 ```rust
 #[must_use]
 struct MustUse {
-  // some fields
+    // some fields
 }
 
 # impl MustUse {
 #   fn new() -> MustUse { MustUse {} }
 # }
 #
 fn main() {
-  // Violates the `unused_must_use` lint.
-  MustUse::new();
+    // 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. The exceptions to this is if the return type
-of the function is `()`, `!`, or a [zero-variant enum], in which case the
-attribute does nothing.
+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 }
 
 fn main() {
-  // Violates the unused_must_use lint.
-  five();
+    // Violates the unused_must_use lint.
+    five();
 }
 ```
 
@@ -193,21 +190,21 @@ when the call expression is a function from an implementation of the trait.
 
 ```rust
 trait Trait {
-  #[must_use]
-  fn use_me(&self) -> i32;
+    #[must_use]
+    fn use_me(&self) -> i32;
 }
 
 impl Trait for i32 {
-  fn use_me(&self) -> i32 { 0i32 }
+    fn use_me(&self) -> i32 { 0i32 }
 }
 
 fn main() {
-  // Violates the `unused_must_use` lint.
-  5i32.use_me();
+    // Violates the `unused_must_use` lint.
+    5i32.use_me();
 }
 ```
 
-When used on a function in an implementation, the attribute does nothing.
+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
@@ -219,14 +216,14 @@ When used on a function in an implementation, the attribute does nothing.
 > fn five() -> i32 { 5i32 }
 >
 > fn main() {
->   // None of these violate the unused_must_use lint.
->   (five(),);
->   Some(five());
->   { five() };
->   if true { five() } else { 0i32 };
->   match true {
->     _ => five()
->   };
+>     // None of these violate the unused_must_use lint.
+>     (five(),);
+>     Some(five());
+>     { five() };
+>     if true { five() } else { 0i32 };
+>     match true {
+>         _ => five()
+>     };
 > }
 > ```
 
@@ -238,17 +235,16 @@ When used on a function in an implementation, the attribute does nothing.
 > fn five() -> i32 { 5i32 }
 >
 > fn main() {
->   // Does not violate the unused_must_use lint.
->   let _ = five();
+>     // Does not violate the unused_must_use lint.
+>     let _ = five();
 > }
 > ```
 
-The `must_use` attribute may also include a message by using the
+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.
 
 [Clippy]: https://github.com/rust-lang/rust-clippy
-[Compiler plugins]: ../unstable-book/language-features/plugin.html#lint-plugins
 [_MetaListNameValueStr_]: attributes.html#meta-item-attribute-syntax
 [_MetaListPaths_]: attributes.html#meta-item-attribute-syntax
 [_MetaNameValueStr_]: attributes.html#meta-item-attribute-syntax
@@ -271,5 +267,5 @@ message will be given alongside the warning.
 [struct]: items/structs.html
 [trait implementation items]: items/implementations.html#trait-implementations
 [trait item]: items/traits.html
+[traits]: items/traits.html
 [union]: items/unions.html
-[zero-variant enum]: items/enumerations.html#zero-variant-enums

src/attributes/compiler-settings.md → src/attributes/limits.md

@@ -1,6 +1,6 @@
-# Compiler setting attributes
+# Limits
 
-The following [attributes] affect internal settings of the compiler.
+The following [attributes] affect compile-time limits.
 
 ## The `recursion_limit` attribute
 

src/attributes/testing.md

@@ -7,11 +7,10 @@ enables the [`test` conditional compilation option].
 
 ## The `test` attribute
 
-The *`test` attribute* marks a function to be executed as a test when the
-crate is compiled in test mode. These functions are only compiled when
-compiling in test mode. Test functions must take no arguments, must not
-declare any [trait or lifetime bounds], must not have any [where clauses], and
-its return type must be one of the following:
+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`
@@ -28,8 +27,8 @@ its return type must be one of the following:
 > or using `cargo test`.
 
 Tests that return `()` pass as long as they terminate and do not panic. Tests
-that return a `Result` pass as long as they return `Ok(())`. Tests that do not
-terminate neither pass nor fail.
+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;
@@ -47,8 +46,7 @@ fn test_the_thing() -> io::Result<()> {
 
 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 only be compiled when compiling
-with the test harness.
+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.

src/items/extern-crates.md

@@ -93,7 +93,7 @@ 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