Rollup merge of rust-lang#39084 - sphela:book-update-patterns, r=stev…

…eklabnik

An update to patterns documentation

As it is written the current pattern page creates a lot of confusion, even for someone with previous rust experience. It's so hard because it introduces an entirely new language feature without explaining. Someone could update it within the span of a few minutes by just explaining the newly introduced feature.

```rust
match c {
    x => println!("x: {} c: {}", x, c),
}
```
No where in the book up to this point has it explained that identifiers match patterns with just a name create an irrefutable pattern. The page uses this feature without explanation, it just assumes that readers would immediately understand it. To confuse the issue even further the topic uses this feature to explain shadowing, placing two x's from different scopes and different meanings without ever explaining why there is shadowing.

What follows comes across as utterly nonsensical given everything the reader would know about Rust about this point:

```rust
the result:
x: c c: c
x: x
```

x is c? What? Yes even if you understand that x here is not the x in the previous scope why would x equal 'c' here? What previous chapter explained this? The previous chapter on 'matching' only mentions the catch all '_' and never in any shape or form mentioned that a name here creates an irrefutable pattern and binds a value.

There are numerous examples of people not understanding this section, not finding answers and looking for them online about `x: c c: c`:

rust-lang/book#316

https://stackoverflow.com/questions/35563141/match-shadowing-example-in-the-patterns-section-of-the-rust-book-is-very-perplex

https://users.rust-lang.org/t/confusion-about-match-and-patterns/3937

https://www.bountysource.com/issues/38852461-question-on-patterns-section-shadowing-example-existing-book

And a [google search for `rust x: c c: c`](https://www.google.com/search?q=rust+%22x:+c+c:+c%22) finds many more people being tripped up, including people who speak a language other than English. I am confident that this page has resulted in questions on the irc channel more than once. Given rust already has a pretty big learning curve I recommend this be fixed.

I was asked to create PR from where I made this same case in the [rust book repository issue](rust-lang/book#316) (I didn't realize this was a separate project).

src/doc/book/patterns.md

@@ -23,6 +23,33 @@ match x {
 
 This prints `one`.
 
+It's possible to create a binding for the value in the any case:
+
+```rust
+let x = 1;
+
+match x {
+    y => println!("x: {} y: {}", x, y),
+}
+```
+
+This prints:
+
+```text
+x: 1 y: 1
+```
+
+Note it is an error to have both a catch-all `_` and a catch-all binding in the same match block:
+
+```rust
+let x = 1;
+
+match x {
+    y => println!("x: {} y: {}", x, y),
+    _ => println!("anything"), // this causes an error as it is unreachable
+}
+```
+
 There’s one pitfall with patterns: like anything that introduces a new binding,
 they introduce shadowing. For example: