be more direct about borrow requirenments

Author: matklad

src/libcore/borrow.rs

@@ -32,6 +32,10 @@
 /// on the identical behavior of these additional trait implementations.
 /// These traits will likely appear as additional trait bounds.
 ///
+/// In particular `Eq`, `Ord` and `Hash` must be equivalent for
+/// borrowed and owned values: `x.borrow() == y.borrow()` should give the
+/// same result as `x == y`.
+///
 /// If generic code merely needs to work for all types that can
 /// provide a reference to related type `T`, it is often better to use
 /// [`AsRef<T>`] as more types can safely implement it.

src/libcore/convert.rs

@@ -105,11 +105,13 @@ pub const fn identity<T>(x: T) -> T { x }
 /// `&T` or write a custom function.
 ///
 ///
-/// `AsRef` is very similar to, but serves a slightly different purpose than [`Borrow`]:
+/// `AsRef` has the same signature as [`Borrow`], but `Borrow` is different in few aspects:
 ///
-/// - Use `AsRef` when the goal is to simply convert into a reference
-/// - Use `Borrow` when the goal is related to writing code that is agnostic to
-///   the type of borrow and whether it is a reference or value
+/// - Unlike `AsRef`, `Borrow` has a blanket impl for any `T`, and can be used to accept either
+///   a reference or a value.
+/// - `Borrow` also requires that `Hash`, `Eq` and `Ord` for borrowed value are
+///   equivalent to those of the owned value. For this reason, if you want to
+///   borrow only a single field of a struct you can implement `AsRef`, but not `Borrow`.
 ///
 /// [`Borrow`]: ../../std/borrow/trait.Borrow.html
 ///