Updates for Centril's review.

rust-lang · Mar 16, 2019 · 5bbf146 · 5bbf146
1 parent fdfcd8b
commit 5bbf146
Show file tree

Hide file tree

Showing 8 changed files with 78 additions and 77 deletions.
diff --git a/src/SUMMARY.md b/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)

diff --git a/src/attributes.md b/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

diff --git a/src/attributes/codegen.md b/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
 

diff --git a/src/attributes/derive.md b/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
diff --git a/src/attributes/diagnostics.md b/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
diff --git a/src/attributes/compiler-settings.md → src/attributes/limits.md b/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
 

diff --git a/src/attributes/testing.md b/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.

diff --git a/src/items/extern-crates.md b/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