Merge branch 'master' into formatting-fixes

Author: alercah

src/attributes.md

@@ -166,9 +166,6 @@ 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.
-- `must_use` - on structs and enums, will warn if a value of this type isn't used or
-   assigned to a variable. You may also include an optional message by using
-   `#[must_use = "message"]` which will be given alongside the warning.
 
 ### Deprecation
 
@@ -325,7 +322,7 @@ The lint checks supported by the compiler can be found via `rustc -W help`,
 along with their default settings.  [Compiler
 plugins][unstable book plugin] can provide additional lint checks.
 
-```rust,ignore
+```rust
 pub mod m1 {
     // Missing documentation is ignored here
     #[allow(missing_docs)]
@@ -366,7 +363,7 @@ pub mod m2{
 This example shows how one can use `forbid` to disallow uses of `allow` for
 that lint check:
 
-```rust,ignore
+```rust,compile_fail
 #[forbid(missing_docs)]
 pub mod m3 {
     // Attempting to toggle warning signals an error here
@@ -376,6 +373,105 @@ pub mod m3 {
 }
 ```
 
+#### `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].
+
+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 {} }
+# }
+#
+fn main() {
+  // 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.
+
+```rust
+#[must_use]
+fn five() -> i32 { 5i32 }
+
+fn main() {
+  // Violates the unused_must_use lint.
+  five();
+}
+```
+
+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 }
+}
+
+fn main() {
+  // Violates the `unused_must_use` lint.
+  5i32.use_me();
+}
+```
+
+When used on a function in an 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 }
+>
+> fn main() {
+>   // 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 }
+>
+> fn main() {
+>   // Does not violate the unused_must_use lint.
+>   let _ = five();
+> }
+> ```
+
+The `must_use` attribute may also include a message by using
+`#[must_use = "message"]`. The message will be given alongside the warning.
+
 ### Inline attribute
 
 The inline attribute suggests that the compiler should place a copy of
@@ -430,4 +526,15 @@ You can implement `derive` for your own type through [procedural macros].
 [Doc comments]: comments.html#doc-comments
 [The Rustdoc Book]: ../rustdoc/the-doc-attribute.html
 [procedural macros]: procedural-macros.html
+[struct]: items/structs.html
+[enum]: items/enumerations.html
+[union]: items/unions.html
+[functions]: items/functions.html
+[expression]: expressions.html
+[expression statement]: statements.html#expression-statements
+[call expression]: expressions/call-expr.html
+[block expression]: expressions/block-expr.html
+[`Drop`]: special-types-and-traits.html#drop
+[let statement]: statements.html#let-statements
 [unstable book plugin]: ../unstable-book/language-features/plugin.html#lint-plugins
+[zero-variant enum]: enumerations.html#zero-variant-enums

src/destructors.md

@@ -2,11 +2,11 @@
 
 When an [initialized] [variable] in Rust goes out of scope or a [temporary]
 is no longer needed its _destructor_ is run. [Assignment] also runs the
-destructor of its left-hand operand, unless it's an unitialized variable. If a
+destructor of its left-hand operand, unless it's an uninitialized variable. If a
 [struct] variable has been partially initialized, only its initialized fields
 are dropped.
 
-The destrutor of a type consists of
+The destructor of a type consists of
 
 1. Calling its [`std::ops::Drop::drop`] method, if it has one.
 2. Recursively running the destructor of all of its fields.

src/dynamically-sized-types.md

@@ -14,7 +14,7 @@ types">DSTs</abbr>. Such types can only be used in certain cases:
   type arguments when a bound of `?Sized`. By default any type parameter
   has a `Sized` bound.
 * Traits may be implemented for <abbr title="dynamically sized
-  types">DSTs</abbr>. Unlike type parameters`Self: ?Sized` by default in trait
+  types">DSTs</abbr>. Unlike type parameters `Self: ?Sized` by default in trait
   definitions.
 * Structs may contain a <abbr title="dynamically sized type">DST</abbr> as the
   last field, this makes the struct itself a

src/expressions.md

@@ -44,8 +44,8 @@ and blocks again can recursively nest inside each other to an arbitrary depth.
 ## Expression precedence
 
 The precedence of Rust operators and expressions is ordered as follows, going
-from strong to weak. Binary Operators at the same precedence level are
-evaluated in the order given by their associativity.
+from strong to weak. Binary Operators at the same precedence level are grouped
+in the order given by their associativity.
 
 | Operator/Expression         | Associativity       |
 |-----------------------------|---------------------|
@@ -55,7 +55,7 @@ evaluated in the order given by their associativity.
 | Function calls, array indexing |                  |
 | `?`                         |                     |
 | Unary `-` `*` `!` `&` `&mut` |                    |
-| `as` `:`                    | left to right       |
+| `as`                        | left to right       |
 | `*` `/` `%`                 | left to right       |
 | `+` `-`                     | left to right       |
 | `<<` `>>`                   | left to right       |
@@ -66,7 +66,6 @@ evaluated in the order given by their associativity.
 | `&&`                        | left to right       |
 | <code>&#124;&#124;</code>   | left to right       |
 | `..` `..=`                  | Require parentheses |
-| `<-`                        | right to left       |
 | `=` `+=` `-=` `*=` `/=` `%=` <br> `&=` <code>&#124;=</code> `^=` `<<=` `>>=` | right to left |
 | `return` `break` closures   |                     |
 

src/expressions/match-expr.md

@@ -18,7 +18,7 @@
 > &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> _MatchArmPatterns_ _MatchArmGuard_<sup>?</sup>  
 >
 > _MatchArmPatterns_ :  
-> &nbsp;&nbsp; `|`<sup>?</sup> _Pattern_ ( `|` _Pattern_ )<sup>*</sup>  
+> &nbsp;&nbsp; `|`<sup>?</sup> _Pattern_ ( `|` _Pattern_ )<sup>\*</sup>  
 >
 > _MatchArmGuard_ :  
 > &nbsp;&nbsp; `if` [_Expression_]
@@ -140,6 +140,25 @@ backwards compatibility.
 Range patterns only work [`char`] and [numeric types]. A range pattern may not
 be a sub-range of another range pattern inside the same `match`.
 
+Slice patterns can match both arrays of fixed size and slices of dynamic size.
+```rust
+// Fixed size
+let arr = [1, 2, 3];
+match arr {
+    [1, _, _] => "starts with one",
+    [a, b, c] => "starts with something else",
+};
+```
+```rust
+// Dynamic size
+let v = vec![1, 2, 3];
+match v[..] {
+    [a, b] => { /* this arm will not apply because the length doesn't match */ }
+    [a, b, c] => { /* this arm will apply */ }
+    _ => { /* this wildcard is required, since we don't know length statically */ }
+}
+```
+
 Finally, match patterns can accept *pattern guards* to further refine the
 criteria for matching a case. Pattern guards appear after the pattern and
 consist of a bool-typed expression following the `if` keyword. A pattern guard
@@ -164,4 +183,3 @@ let message = match maybe_digit {
 [numeric types]: types.html#numeric-types
 [_InnerAttribute_]: attributes.html
 [_OuterAttribute_]: attributes.html
-[range]: range-expr.html

src/expressions/method-call-expr.md

@@ -2,10 +2,10 @@
 
 A _method call_ consists of an expression (the *receiver*) followed by a single
 dot, an [identifier], and a parenthesized expression-list. Method calls are
-resolved to methods on specific traits, either statically dispatching to a
-method if the exact `self`-type of the left-hand-side is known, or dynamically
-dispatching if the left-hand-side expression is an indirect [trait
-object](types.html#trait-objects).
+resolved to associated [methods] on specific traits, either statically
+dispatching to a method if the exact `self`-type of the left-hand-side is known,
+or dynamically dispatching if the left-hand-side expression is an indirect
+[trait object](types.html#trait-objects).
 
 ```rust
 let pi: Result<f32, _> = "3.14".parse();
@@ -95,3 +95,4 @@ and function invocation.
 [trait objects]: types.html#trait-objects
 [disambiguate call]: expressions/call-expr.html#disambiguating-function-calls
 [dereference]: expressions/operator-expr.html#the-dereference-operator
+[methods]: items/associated-items.html#methods

src/expressions/operator-expr.md

@@ -109,14 +109,14 @@ assert_eq!(*y, 11);
 > _ErrorPropagationExpression_ :  
 >    [_Expression_] `?`  
 
-The question mark operator (`?`) unwraps valid values or returns errornous
+The question mark operator (`?`) unwraps valid values or returns erroneous
 values, propagating them to the calling function. It is a unary postfix
 operator that can only be applied to the types `Result<T, E>` and `Option<T>`.
 
 When applied to values of the `Result<T, E>` type, it propagates errors. If 
 the value is `Err(e)`, then it will return `Err(From::from(e))` from the
 enclosing function or closure. If applied to `Ok(x)`, then it will unwrap the
-value to evaulate to `x`.
+value to evaluate to `x`.
 
 ```rust
 # use std::num::ParseIntError;
@@ -393,7 +393,7 @@ An _assignment expression_ consists of a [place expression] followed by an
 equals sign (`=`) and a [value expression].
 
 Evaluating an assignment expression [drops](destructors.html) the left-hand
-operand, unless it's an unitialized local variable or field of a local variable,
+operand, unless it's an uninitialized local variable or field of a local variable,
 and [either copies or moves](expressions.html#moved-and-copied-types) its
 right-hand operand to its left-hand operand. The left-hand operand must be a
 place expression: using a value expression results in a compiler error, rather
@@ -444,7 +444,7 @@ assert_eq!(x, 14);
 
 [_BorrowExpression_]: #borrow-operators
 [_DereferenceExpression_]: #the-dereference-operator
-[_ErrorPropagationExpression_]: #the--operator
+[_ErrorPropagationExpression_]: #the-question-mark-operator
 [_NegationExpression_]: #negation-operators
 [_ArithmeticOrLogicalExpression_]: #arithmetic-and-logical-binary-operators
 [_ComparisonExpression_]: #comparison-operators

src/items/associated-items.md

@@ -33,7 +33,7 @@ The identifier if the name of the function. The generics, parameter list,
 return type, and where clause of the associated function must be the same as the
 associated function declarations's.
 
-An *associated function definiton* defines a function associated with another
+An *associated function definition* defines a function associated with another
 type. It is written the same as a [function item].
 
 An example of a common associated function is a `new` function that returns
@@ -77,15 +77,19 @@ let _: f64 = <f64 as Num>::from_i32(42);
 let _: f64 = f64::from_i32(42);
 ```
 
+### Methods
+
 Associated functions whose first parameter is named `self` are called *methods*
 and may be invoked using the [method call operator], for example, `x.foo()`, as
 well as the usual function call notation.
 
-When the first parameter is named `self`, the following shorthands may be used.
+The `self` parameter must have one of the following types. As a result, the
+following shorthands may be used to declare `self`:
 
 * `self` -> `self: Self`
 * `&'lifetime self` -> `self: &'lifetime Self`
 * `&'lifetime mut self` -> `self: &'lifetime mut Self`
+* `self : Box<Self>` (no shorthand)
 
 > Note: Lifetimes can be and usually are elided with this shorthand.
 

src/items/constant-items.md

@@ -61,7 +61,7 @@ fn create_and_drop_zero_with_destructor() {
 ```
 
 [constant value]: expressions.html#constant-expressions
-[static lifetime elision]: items/lifetime-elision.html#static-lifetime-elision
+[static lifetime elision]: lifetime-elision.html#static-lifetime-elision
 [`Drop`]: special-types-and-traits.html#drop
 [IDENTIFIER]: identifiers.html
 [_Type_]: types.html

src/items/functions.md

@@ -7,16 +7,10 @@ as parameters, through which the caller passes arguments into the function, and
 the *output* [*type*][type] of the value the function will return to its caller
 on completion.
 
-[block]: expressions/block-expr.html
-[variables]: variables.html
-[type]: types.html
-
 When referred to, a _function_ yields a first-class *value* of the
 corresponding zero-sized [*function item type*], which
 when called evaluates to a direct call to the function.
 
-[*function item type*]: types.html#function-item-types
-
 For example, this is a simple function:
 ```rust
 fn answer_to_life_the_universe_and_everything() -> i32 {
@@ -61,7 +55,7 @@ fn foo<A, B>(x: A, y: B) {
 ```
 
 Inside the function signature and body, the name of the type parameter can be
-used as a type name. [Trait](items/traits.html) bounds can be specified for type
+used as a type name. [Trait] bounds can be specified for type
 parameters to allow methods with that trait to be called on values of that
 type. This is specified using the `where` syntax:
 
@@ -91,8 +85,6 @@ component after the function name. This might be necessary if there is not
 sufficient context to determine the type parameters. For example,
 `mem::size_of::<u32>() == 4`.
 
-[path]: paths.html
-
 ## Extern functions
 
 Extern functions are part of Rust's foreign function interface, providing the
@@ -124,3 +116,9 @@ of an extern function will cause the process to abort. In LLVM, this is
 implemented by executing an illegal instruction.
 
 [external blocks]: items/external-blocks.html
+[path]: paths.html
+[block]: expressions/block-expr.html
+[variables]: variables.html
+[type]: types.html
+[*function item type*]: types.html#function-item-types
+[Trait]: items/traits.html