Documentation misleadingly implies that auto-cross-borrowing still occurs

[bstrie]

http://doc.rust-lang.org/guide-pointers.html#best-practices

Use references when you want to use a pointer, but do not want to take ownership. References just borrow ownership, which is more polite if you don't need the ownership. In other words, prefer:

fn succ(x: &int) -> int { *x + 1 }

to

fn succ(x: Box<int>) -> int { *x + 1 }

As a corollary to that rule, references allow you to accept a wide variety of other pointers, and so are useful so that you don't have to write a number of variants per pointer. In other words, prefer:

fn succ(x: &int) -> int { *x + 1 }

to

fn box_succ(x: Box<int>) -> int { *x + 1 }

fn rc_succ(x: std::rc::Rc<int>) -> int { *x + 1 }

In the past, a function accepting &int could seamlessly accept an input of type Box<int> (or ~int, rather), what we (I think) we used to call auto-cross-borrowing. But in today's rust you must deref-and-borrow at the call site manually via &*. Mention this last fact as a part of this doc chunk.

[bstrie]

cc @steveklabnik