Rollup merge of rust-lang#33353 - timothy-mcroy:E0502, r=steveklabnik

Add error explanation for E0502

I am questioning the order of presentation on the suggested code fixes, but I'm not sure what would be best.  Thoughts?

r? @GuillaumeGomez

Author: eddyb

src/librustc_borrowck/diagnostics.rs

@@ -501,6 +501,33 @@ fn foo(a: &mut i32) {
 ```
 "##,
 
+E0502: r##"
+This error indicates that you are trying to borrow a variable as mutable when it
+has already been borrowed as immutable.
+
+Example of erroneous code:
+
+```compile_fail
+fn bar(x: &mut i32) {}
+fn foo(a: &mut i32) {
+    let ref y = a; // a is borrowed as immutable.
+    bar(a); // error: cannot borrow `*a` as mutable because `a` is also borrowed
+            //        as immutable
+}
+```
+To fix this error, ensure that you don't have any other references to the
+variable before trying to access it mutably:
+```
+fn bar(x: &mut i32) {}
+fn foo(a: &mut i32) {
+    bar(a);
+    let ref y = a; // ok!
+}
+```
+For more information on the rust ownership system, take a look at
+https://doc.rust-lang.org/stable/book/references-and-borrowing.html.
+"##,
+
 E0504: r##"
 This error occurs when an attempt is made to move a borrowed variable into a
 closure.