librustc: Remove cross-borrowing of `Box<T>` to `&T` from the language,

except where trait objects are involved.

Part of issue #15349, though I'm leaving it open for trait objects.
Cross borrowing for trait objects remains because it is needed until we
have DST.

This will break code like:

    fn foo(x: &int) { ... }

    let a = box 3i;
    foo(a);

Change this code to:

    fn foo(x: &int) { ... }

    let a = box 3i;
    foo(&*a);

[breaking-change]

4 files changed, 10 insertions, 13 deletions

diff --git a/src/doc/guide-lifetimes.md b/src/doc/guide-lifetimes.md
index 1f44b77d56a..a6cc9cd0bc2 100644
--- a/src/doc/guide-lifetimes.md
+++ b/src/doc/guide-lifetimes.md
@@ -67,7 +67,7 @@ Now we can call `compute_distance()`:
 # let on_the_stack :     Point  =     Point{x: 3.0, y: 4.0};
 # let on_the_heap  : Box<Point> = box Point{x: 7.0, y: 9.0};
 # fn compute_distance(p1: &Point, p2: &Point) -> f64 { 0.0 }
-compute_distance(&on_the_stack, on_the_heap);
+compute_distance(&on_the_stack, &*on_the_heap);
 ~~~
 
 Here, the `&` operator takes the address of the variable
@@ -77,10 +77,9 @@ value. We also call this _borrowing_ the local variable
 `on_the_stack`, because we have created an alias: that is, another
 name for the same data.
 
-In the case of `on_the_heap`, however, no explicit action is necessary. 
-The compiler will automatically convert a box point to a reference like &point. 
-This is another form of borrowing; in this case, the contents of the owned box 
-are being lent out.
+Likewise, in the case of `owned_box`,
+the `&` operator is used in conjunction with the `*` operator
+to take a reference to the contents of the box.
 
 Whenever a caller lends data to a callee, there are some limitations on what
 the caller can do with the original. For example, if the contents of a
diff --git a/src/doc/guide-pointers.md b/src/doc/guide-pointers.md
index 08652822097..17a1114be55 100644
--- a/src/doc/guide-pointers.md
+++ b/src/doc/guide-pointers.md
@@ -279,7 +279,7 @@ fn main() {
     let origin =    &Point { x: 0.0, y: 0.0 };
     let p1     = box Point { x: 5.0, y: 3.0 };
 
-    println!("{}", compute_distance(origin, p1));
+    println!("{}", compute_distance(origin, &*p1));
 }
 ~~~
 
diff --git a/src/doc/rust.md b/src/doc/rust.md
index 9d5a6fa42a8..9fe61eb3fe3 100644
--- a/src/doc/rust.md
+++ b/src/doc/rust.md
@@ -3243,7 +3243,7 @@ enum List { Nil, Cons(uint, Box<List>) }
 fn is_sorted(list: &List) -> bool {
     match *list {
         Nil | Cons(_, box Nil) => true,
-        Cons(x, ref r @ box Cons(y, _)) => (x <= y) && is_sorted(*r)
+        Cons(x, ref r @ box Cons(y, _)) => (x <= y) && is_sorted(&**r)
     }
 }
 
diff --git a/src/doc/tutorial.md b/src/doc/tutorial.md
index e0f0bbd6c9f..4c90e564b58 100644
--- a/src/doc/tutorial.md
+++ b/src/doc/tutorial.md
@@ -1470,7 +1470,7 @@ Now we can call `compute_distance()` in various ways:
 # let on_the_stack :     Point  =     Point { x: 3.0, y: 4.0 };
 # let on_the_heap  : Box<Point> = box Point { x: 7.0, y: 9.0 };
 # fn compute_distance(p1: &Point, p2: &Point) -> f64 { 0.0 }
-compute_distance(&on_the_stack, on_the_heap);
+compute_distance(&on_the_stack, &*on_the_heap);
 ~~~
 
 Here the `&` operator is used to take the address of the variable
@@ -1480,11 +1480,9 @@ reference. We also call this _borrowing_ the local variable
 `on_the_stack`, because we are creating an alias: that is, another
 route to the same data.
 
-In the case of `owned_box`, however, no
-explicit action is necessary. The compiler will automatically convert
-a box `box point` to a reference like
-`&point`. This is another form of borrowing; in this case, the
-contents of the owned box are being lent out.
+Likewise, in the case of `owned_box`,
+the `&` operator is used in conjunction with the `*` operator
+to take a reference to the contents of the box.
 
 Whenever a value is borrowed, there are some limitations on what you
 can do with the original. For example, if the contents of a variable