Address patterns review comments.

Author: ehuss

src/expressions/match-expr.md

@@ -24,9 +24,9 @@
 >    `if` [_Expression_]
 
 A *`match` expression* branches on a pattern. The exact form of matching that
-occurs depends on the pattern. See [Patterns] for more details. A `match`
+occurs depends on the [pattern][Patterns]. A `match`
 expression has a *head expression*, which is the value to compare to the
-patterns. The type of the patterns must equal the type of the head expression.
+patterns. The head expression and the patterns must have the same type.
 
 A `match` behaves differently depending on whether or not the head expression
 is a [place expression or value expression][place expression].
@@ -59,10 +59,8 @@ match x {
 }
 ```
 
-Patterns that bind variables default to binding to a copy or move of the
-matched value (depending on the matched value's type). This can be changed to
-bind to a reference by using the `ref` keyword, or to a mutable reference using
-`ref mut`. See [Identifier Patterns].
+Variables bound within the pattern are scoped to the match guard and the arm's
+expression. The [binding mode] (move, copy, or reference) depends on the pattern.
 
 Multiple match patterns may be joined with the `|` operator:
 
@@ -139,3 +137,4 @@ meaning on match arms are [`cfg`], `cold`, and the [lint check attributes].
 [Tuple Struct Patterns]: patterns.html#tuplestruct-patterns
 [Tuple Patterns]: patterns.html#tuple-patterns
 [Range Pattern]: patterns.html#range-patterns
+[binding mode]: patterns.html#binding-modes

src/patterns.md

@@ -13,11 +13,9 @@
 >    | [_SlicePattern_]\
 >    | [_PathPattern_]
 
-Patterns in Rust are used to match values against structures and to,
+Patterns are used to match values against structures and to,
 optionally, bind variables to values inside these structures. They are also
-used in variable declarations and function/closure parameters, though in these
-cases most of the time they are simply used as an identifier that binds to a
-value.
+used in variable declarations and parameters for functions and closures.
 
 For example, the pattern used in:
 
@@ -65,17 +63,17 @@ Patterns are used in:
 * [`if let` expressions](expressions/if-expr.html)
 * [`while let` expressions](expressions/loop-expr.html#predicate-pattern-loops)
 * [`for` expressions](expressions/loop-expr.html#iterator-loops)
-* Inside other patterns
 
 ## Destructuring
 
-Patterns can be used to *destructure* structs, enums, and tuples. Destructuring
-breaks a value up into its component pieces. The syntax used is almost the same as
-when creating such values. When destructing a data structure with named (but
-not numbered) fields, it is allowed to write `fieldname` as a shorthand for
-`fieldname: fieldname`. In a pattern whose head expression has a `struct`,
-`enum` or `tuple` type, a placeholder (`_`) stands for a *single* data field,
-whereas a wildcard `..` stands for *all* the remaining fields of a particular variant.
+Patterns can be used to *destructure* [structs], [enums], and [tuples].
+Destructuring breaks up a value into its component pieces. The syntax used is
+almost the same as when creating such values. In a pattern whose head
+expression has a `struct`, `enum` or `tuple` type, a placeholder (`_`) stands
+in for a *single* data field, whereas a wildcard `..` stands in for *all* the
+remaining fields of a particular variant. When destructuring a data structure
+with named (but not numbered) fields, it is allowed to write `fieldname` as a
+shorthand for `fieldname: fieldname`.
 
 ```rust
 # enum Message {
@@ -98,7 +96,7 @@ match message {
 
 ## Refutability
 
-A pattern is said to be *Refutable* when it **has the possibility of not being matched**
+A pattern is said to be *refutable* when it has the possibility of not being matched
 by the value it is being matched against. *Irrefutable* patterns, on the other hand,
 always match the value they are being matched against. Examples:
 
@@ -136,14 +134,19 @@ if let (a, 3) = (1, 2) {           // "(a, 3)" is refutable, and will not match
 [INTEGER_LITERAL]: tokens.html#integer-literals
 [FLOAT_LITERAL]: tokens.html#floating-point-literals
 
-_Literal patterns_ match exactly the value they represent. Since negative numbers are
-not literals in Rust, literal patterns also accept an optional minus sign before the
-literal.
+_Literal patterns_ match exactly the same value as what is created by the
+literal. Since negative numbers are not [literals], literal patterns also
+accept an optional minus sign before the literal, which acts like the negation
+operator.
+
+<div class="warning">
 
 Floating-point literals are currently accepted, but due to the complexity of comparing
 them, they are going to be forbidden on literal patterns in a future version of Rust (see
 [issue #41620](https://github.com/rust-lang/rust/issues/41620)).
 
+</div>
+
 Literal patterns are always refutable.
 
 Examples:
@@ -165,7 +168,10 @@ for i in -2..5 {
 > _IdentifierPattern_ :\
 > &nbsp;&nbsp; &nbsp;&nbsp; `ref`<sup>?</sup> `mut`<sup>?</sup> [IDENTIFIER] (`@` [_Pattern_] ) <sup>?</sup>
 
-_Identifier patterns_ bind the value they match to a **previously undeclared** variable.
+Identifier patterns bind the value they match to a variable. The identifier
+must be unique within the pattern. The variable will shadow any variables of
+the same name in scope. The scope of the new binding depends on the context of
+where the pattern is used (such as a `let` binding versus a `match` arm).
 
 Patterns that consist of only an identifier, possibly with a `mut`, like
 `variable`, `x`, and `y` below:
@@ -178,7 +184,7 @@ fn sum(x: i32, y: i32) -> i32 {
 ```
 
 match any value and bind it to that identifier. This is the most commonly
-used pattern in variable declarations and function/closure parameters.
+used pattern in variable declarations and parameters for functions and closures.
 
 To bind non-trivial patterns to a variable, the use of the syntax `variable @
 subpattern` is needed. For example:
@@ -195,7 +201,7 @@ match x {
 binds to `e` the value 2 (not the entire range: the range here is a range subpattern).
 
 By default, identifier patterns bind a variable to a copy of or move from the
-matched value (depending whether the matched value implements the [Copy trait]).
+matched value depending on whether the matched value implements [Copy].
 This can be changed to bind to a reference by using the `ref` keyword,
 or to a mutable reference using `ref mut`. For example:
 
@@ -642,5 +648,9 @@ refer to refutable constants or enum variants for enums with multiple variants.
 [_SlicePattern_]: #slice-patterns
 [_PathPattern_]: #path-patterns
 
-[Copy trait]: special-types-and-traits.html#copy
+[Copy]: special-types-and-traits.html#copy
 [IDENTIFIER]: identifiers.html
+[enums]: items/enumerations.html
+[literals]: expressions/literal-expr.html
+[structs]: items/structs.html
+[tuples]: types.html#tuple-types

src/tokens.md

@@ -577,42 +577,42 @@ them are referred to as "token trees" in [macros].  The three types of brackets
 
 
 [Operator expressions]: expressions/operator-expr.html
-[tokens]: #tokens
-[keywords]: keywords.html
-[identifier]: identifiers.html
-[tuples]: types.html#tuple-types
-[tuple structs]: items/structs.html
-[tuple variants]: items/enumerations.html
+[Range patterns]: patterns.html#range-patterns
+[Reference patterns]: patterns.html#reference-patterns
+[Subpattern binding]: patterns.html#identifier-patterns
+[Wildcard patterns]: patterns.html#wildcard-pattern
 [arith]: expressions/operator-expr.html#arithmetic-and-logical-binary-operators
-[negation]: expressions/operator-expr.html#negation-operators
-[lazy-bool]: expressions/operator-expr.html#lazy-boolean-operators
-[compound]: expressions/operator-expr.html#compound-assignment-expressions
-[comparison]: expressions/operator-expr.html#comparison-operators
-[match]: expressions/match-expr.html
-[field]: expressions/field-expr.html
-[range]: expressions/range-expr.html
-[trait bounds]: trait-bounds.html
-[dereference]: expressions/operator-expr.html#the-dereference-operator
-[raw pointers]: types.html#raw-pointers-const-and-mut
-[macros]: macros-by-example.html
+[array types]: types.html#array-and-slice-types
+[assignment]: expressions/operator-expr.html#assignment-expressions
 [attributes]: attributes.html
-[never type]: types.html#never-type
 [borrow]: expressions/operator-expr.html#borrow-operators
-[references]: types.html#pointer-types
 [closures]: expressions/closure-expr.html
-[assignment]: expressions/operator-expr.html#assignment-expressions
+[comparison]: expressions/operator-expr.html#comparison-operators
+[compound]: expressions/operator-expr.html#compound-assignment-expressions
 [constant items]: items/constant-items.html
+[dereference]: expressions/operator-expr.html#the-dereference-operator
+[extern]: items/external-blocks.html
+[field]: expressions/field-expr.html
+[functions]: items/functions.html
 [generics]: items/generics.html
+[identifier]: identifiers.html
+[keywords]: keywords.html
+[lazy-bool]: expressions/operator-expr.html#lazy-boolean-operators
+[macros]: macros-by-example.html
+[match]: expressions/match-expr.html
+[negation]: expressions/operator-expr.html#negation-operators
+[never type]: types.html#never-type
 [paths]: paths.html
-[array types]: types.html#array-and-slice-types
-[functions]: items/functions.html
+[patterns]: patterns.html
 [question]: expressions/operator-expr.html#the-question-mark-operator
+[range]: expressions/range-expr.html
+[raw pointers]: types.html#raw-pointers-const-and-mut
+[references]: types.html#pointer-types
 [sized]: trait-bounds.html#sized
-[extern]: items/external-blocks.html
 [struct expressions]: expressions/struct-expr.html
+[tokens]: #tokens
+[trait bounds]: trait-bounds.html
 [tuple index]: expressions/tuple-expr.html#tuple-indexing-expressions
-[Wildcard patterns]: patterns.html#wildcard-pattern
-[patterns]: patterns.html
-[Subpattern binding]: patterns.html#identifier-patterns
-[Range patterns]: patterns.html#range-patterns
-[Reference patterns]: patterns.html#reference-patterns
+[tuple structs]: items/structs.html
+[tuple variants]: items/enumerations.html
+[tuples]: types.html#tuple-types