Auto merge of #24431 - ruud-v-a:explain, r=alexcrichton

This resolves part of #24407.

src/librustc/diagnostics.rs

@@ -112,6 +112,100 @@ reference when using guards or refactor the entire expression, perhaps by
 putting the condition inside the body of the arm.
 "##,
 
+E0162: r##"
+An if-let pattern attempts to match the pattern, and enters the body if the
+match was succesful. If the match is irrefutable (when it cannot fail to match),
+use a regular `let`-binding instead. For instance:
+
+struct Irrefutable(i32);
+let irr = Irrefutable(0);
+
+// This fails to compile because the match is irrefutable.
+if let Irrefutable(x) = irr {
+    // This body will always be executed.
+    foo(x);
+}
+
+// Try this instead:
+let Irrefutable(x) = irr;
+foo(x);
+"##,
+
+E0165: r##"
+A while-let pattern attempts to match the pattern, and enters the body if the
+match was succesful. If the match is irrefutable (when it cannot fail to match),
+use a regular `let`-binding inside a `loop` instead. For instance:
+
+struct Irrefutable(i32);
+let irr = Irrefutable(0);
+
+// This fails to compile because the match is irrefutable.
+while let Irrefutable(x) = irr {
+    ...
+}
+
+// Try this instead:
+loop {
+    let Irrefutable(x) = irr;
+    ...
+}
+"##,
+
+E0297: r##"
+Patterns used to bind names must be irrefutable. That is, they must guarantee
+that a name will be extracted in all cases. Instead of pattern matching the
+loop variable, consider using a `match` or `if let` inside the loop body. For
+instance:
+
+// This fails because `None` is not covered.
+for Some(x) in xs {
+    ...
+}
+
+// Match inside the loop instead:
+for item in xs {
+    match item {
+        Some(x) => ...
+        None => ...
+    }
+}
+
+// Or use `if let`:
+for item in xs {
+    if let Some(x) = item {
+        ...
+    }
+}
+"##,
+
+E0301: r##"
+Mutable borrows are not allowed in pattern guards, because matching cannot have
+side effects. Side effects could alter the matched object or the environment
+on which the match depends in such a way, that the match would not be
+exhaustive. For instance, the following would not match any arm if mutable
+borrows were allowed:
+
+match Some(()) {
+    None => { },
+    option if option.take().is_none() => { /* impossible, option is `Some` */ },
+    Some(_) => { } // When the previous match failed, the option became `None`.
+}
+"##,
+
+E0302: r##"
+Assignments are not allowed in pattern guards, because matching cannot have
+side effects. Side effects could alter the matched object or the environment
+on which the match depends in such a way, that the match would not be
+exhaustive. For instance, the following would not match any arm if assignments
+were allowed:
+
+match Some(()) {
+    None => { },
+    option if { option = None; false } { },
+    Some(_) => { } // When the previous match failed, the option became `None`.
+}
+"##,
+
 E0303: r##"
 In certain cases it is possible for sub-bindings to violate memory safety.
 Updates to the borrow checker in a future version of Rust may remove this
@@ -165,8 +259,6 @@ register_diagnostics! {
     E0152,
     E0158,
     E0161,
-    E0162,
-    E0165,
     E0170,
     E0261, // use of undeclared lifetime name
     E0262, // illegal lifetime parameter name
@@ -194,12 +286,9 @@ register_diagnostics! {
     E0284, // cannot resolve type
     E0285, // overflow evaluation builtin bounds
     E0296, // malformed recursion limit attribute
-    E0297, // refutable pattern in for loop binding
     E0298, // mismatched types between arms
     E0299, // mismatched types between arms
     E0300, // unexpanded macro
-    E0301, // cannot mutable borrow in a pattern guard
-    E0302, // cannot assign in a pattern guard
     E0304, // expected signed integer constant
     E0305, // expected constant
     E0306, // expected positive integer for repeat count