An update to patterns documentation

[btipling]

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.

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:

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 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 (I didn't realize this was a separate project).

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @steveklabnik (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[steveklabnik]

@bors: r+ rollup

this looks great, thanks!

[bors]

📌 Commit 0dad9dc has been approved by steveklabnik

[bors]

⌛ Testing commit 0dad9dc with merge d8b4b20...

[bors]

💔 Test failed - status-travis

[alexcrichton]

@bors: retry * netbsd network failure #39097

…

On Mon, Jan 16, 2017 at 8:12 AM, bors ***@***.***> wrote: 💔 Test failed - status-travis <https://travis-ci.org/rust-lang/rust/builds/192403753> — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#39084 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAD95Lo6MUHnd-l4lrThR1QhFeyLP_qlks5rS5bhgaJpZM4LkBe2> .