Added note about dangling references.

This error can only occur within a function when a borrow of data owned
within the function is returned; and when there are arguments that could
have been returned instead. Therefore, it is always applicable to add a
specific note that links to the relevant rust documentation about
dangling references.

Author: davidtwco

src/librustc_mir/borrow_check/error_reporting.rs

@@ -530,6 +530,15 @@ impl<'cx, 'gcx, 'tcx> MirBorrowckCtxt<'cx, 'gcx, 'tcx> {
                         self.infcx.tcx.hir.name(fn_node_id),
                     )
                 );
+
+                err.note(
+                    "functions cannot return a borrow to data owned within the function's scope, \
+                     functions can only return borrows to data passed as arguments",
+                );
+                err.note(
+                    "to learn more, visit <https://doc.rust-lang.org/book/second-edition/ch04-02-\
+                     references-and-borrowing.html#dangling-references>",
+                );
             } else {
                 err.span_label(
                     drop_span,

src/test/ui/issues/issue-30438-c.nll.stderr

@@ -11,6 +11,9 @@ LL |     &x
 LL |     //~^ ERROR: `x` does not live long enough
 LL | }
    | - ...but `x` is only valid for the duration of the `silly` function, so it is dropped here while still borrowed
+   |
+   = note: functions cannot return a borrow to data owned within the function's scope, functions can only return borrows to data passed as arguments
+   = note: to learn more, visit <https://doc.rust-lang.org/book/second-edition/ch04-02-references-and-borrowing.html#dangling-references>
 
 error: aborting due to previous error
 

src/test/ui/nll/borrowed-universal-error-2.stderr

@@ -11,6 +11,9 @@ LL |     &v
 LL |     //~^ ERROR `v` does not live long enough [E0597]
 LL | }
    | - ...but `v` is only valid for the duration of the `foo` function, so it is dropped here while still borrowed
+   |
+   = note: functions cannot return a borrow to data owned within the function's scope, functions can only return borrows to data passed as arguments
+   = note: to learn more, visit <https://doc.rust-lang.org/book/second-edition/ch04-02-references-and-borrowing.html#dangling-references>
 
 error: aborting due to previous error
 

src/test/ui/nll/issue-52534-1.stderr

@@ -10,6 +10,9 @@ LL |         &x
    |         ^^ `x` would have to be valid for `'0`
 LL |     }
    |     - ...but `x` is only valid for the duration of the `bar` function, so it is dropped here while still borrowed
+   |
+   = note: functions cannot return a borrow to data owned within the function's scope, functions can only return borrows to data passed as arguments
+   = note: to learn more, visit <https://doc.rust-lang.org/book/second-edition/ch04-02-references-and-borrowing.html#dangling-references>
 
 error[E0597]: `x` does not live long enough
   --> $DIR/issue-52534-1.rs:25:5
@@ -23,6 +26,9 @@ LL |     &x
    |     ^^ `x` would have to be valid for `'0`
 LL | }
    | - ...but `x` is only valid for the duration of the `foo` function, so it is dropped here while still borrowed
+   |
+   = note: functions cannot return a borrow to data owned within the function's scope, functions can only return borrows to data passed as arguments
+   = note: to learn more, visit <https://doc.rust-lang.org/book/second-edition/ch04-02-references-and-borrowing.html#dangling-references>
 
 error[E0597]: `x` does not live long enough
   --> $DIR/issue-52534-1.rs:30:6
@@ -36,6 +42,9 @@ LL |     &&x
    |      ^^ `x` would have to be valid for `'0`
 LL | }
    | - ...but `x` is only valid for the duration of the `baz` function, so it is dropped here while still borrowed
+   |
+   = note: functions cannot return a borrow to data owned within the function's scope, functions can only return borrows to data passed as arguments
+   = note: to learn more, visit <https://doc.rust-lang.org/book/second-edition/ch04-02-references-and-borrowing.html#dangling-references>
 
 error[E0597]: borrowed value does not live long enough
   --> $DIR/issue-52534-1.rs:30:6

src/test/ui/nll/issue-52534.stderr

@@ -7,6 +7,9 @@ LL |     foo(|a| &x)
    |          has type `&'0 u32`
 LL | }
    | - ...but `x` is only valid for the duration of the `bar` function, so it is dropped here while still borrowed
+   |
+   = note: functions cannot return a borrow to data owned within the function's scope, functions can only return borrows to data passed as arguments
+   = note: to learn more, visit <https://doc.rust-lang.org/book/second-edition/ch04-02-references-and-borrowing.html#dangling-references>
 
 error[E0597]: `y` does not live long enough
   --> $DIR/issue-52534.rs:27:26
@@ -17,6 +20,9 @@ LL |     baz(|first, second| &y)
    |          has type `&'0 u32`
 LL | }
    | - ...but `y` is only valid for the duration of the `foobar` function, so it is dropped here while still borrowed
+   |
+   = note: functions cannot return a borrow to data owned within the function's scope, functions can only return borrows to data passed as arguments
+   = note: to learn more, visit <https://doc.rust-lang.org/book/second-edition/ch04-02-references-and-borrowing.html#dangling-references>
 
 error: aborting due to 2 previous errors
 

src/test/ui/regions/regions-nested-fns-2.nll.stderr

@@ -9,6 +9,9 @@ LL |             if false { &y } else { z }
 LL |         });
 LL | }
    | - ...but `y` is only valid for the duration of the `nested` function, so it is dropped here while still borrowed
+   |
+   = note: functions cannot return a borrow to data owned within the function's scope, functions can only return borrows to data passed as arguments
+   = note: to learn more, visit <https://doc.rust-lang.org/book/second-edition/ch04-02-references-and-borrowing.html#dangling-references>
 
 error: aborting due to previous error
 

src/test/ui/regions/regions-nested-fns.nll.stderr

@@ -32,6 +32,9 @@ LL |         ay = &y;
 ...
 LL | }
    | - ...but `y` is only valid for the duration of the `nested` function, so it is dropped here while still borrowed
+   |
+   = note: functions cannot return a borrow to data owned within the function's scope, functions can only return borrows to data passed as arguments
+   = note: to learn more, visit <https://doc.rust-lang.org/book/second-edition/ch04-02-references-and-borrowing.html#dangling-references>
 
 error: unsatisfied lifetime constraints
   --> $DIR/regions-nested-fns.rs:23:68