Strengthen documentation discouraging implementing `Into` over `From`

1 files changed, 7 insertions, 9 deletions

diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs
index 9e1501649a2..e5b3af7ad55 100644
--- a/src/libcore/convert.rs
+++ b/src/libcore/convert.rs
@@ -205,11 +205,12 @@ pub trait AsMut<T: ?Sized> {
 /// A value-to-value conversion that consumes the input value. The
 /// opposite of [`From`].
 ///
-/// One should only implement [`Into`] if a conversion to a type outside the current crate is
-/// required. Otherwise one should always prefer implementing [`From`] over [`Into`] because
-/// implementing [`From`] automatically provides one with a implementation of [`Into`] thanks to
-/// the blanket implementation in the standard library. [`From`] cannot do these type of
-/// conversions because of Rust's orphaning rules.
+/// One should avoid implementing [`Into`] and implement [`From`] instead.
+/// Implementing [`From`] automatically provides one with an implementation of [`Into`]
+/// thanks to the blanket implementation in the standard library.
+///
+/// Prefer using [`Into`] over [`From`] when specifying trait bounds on a generic function
+/// to ensure that types that only implement [`Into`] can be used as well.
 ///
 /// **Note: This trait must not fail**. If the conversion can fail, use [`TryInto`].
 ///
@@ -218,7 +219,7 @@ pub trait AsMut<T: ?Sized> {
 /// - [`From`]`<T> for U` implies `Into<U> for T`
 /// - [`Into`] is reflexive, which means that `Into<T> for T` is implemented
 ///
-/// # Implementing [`Into`] for conversions to external types
+/// # Implementing [`Into`] for conversions to external types in old versions of Rust
 ///
 /// Prior to Rust 1.40, if the destination type was not part of the current crate
 /// then you couldn't implement [`From`] directly.
@@ -248,9 +249,6 @@ pub trait AsMut<T: ?Sized> {
 /// (as [`From`] does with [`Into`]). Therefore, you should always try to implement [`From`]
 /// and then fall back to [`Into`] if [`From`] can't be implemented.
 ///
-/// Prefer using [`Into`] over [`From`] when specifying trait bounds on a generic function
-/// to ensure that types that only implement [`Into`] can be used as well.
-///
 /// # Examples
 ///
 /// [`String`] implements [`Into`]`<`[`Vec`]`<`[`u8`]`>>`: