Auto merge of #30901 - mackwic:doc-core-convert, r=steveklabnik

Also add a note about the necessary simplicity of the conversion.
Related issue: #29349

r? @steveklabnik

src/libcore/convert.rs

@@ -17,6 +17,24 @@
 //! Like many traits, these are often used as bounds for generic functions, to
 //! support arguments of multiple types.
 //!
+//! - Impl the `As*` traits for reference-to-reference conversions
+//! - Impl the `Into` trait when you want to consume the value in the conversion
+//! - The `From` trait is the most flexible, usefull for values _and_ references conversions
+//!
+//! As a library writer, you should prefer implementing `From<T>` rather than
+//! `Into<U>`, as `From` provides greater flexibility and offer the equivalent `Into`
+//! implementation for free, thanks to a blanket implementation in the standard library.
+//!
+//! **Note: these traits must not fail**. If the conversion can fail, you must use a dedicated
+//! method which return an `Option<T>` or a `Result<T, E>`.
+//!
+//! # Generic impl
+//!
+//! - `AsRef` and `AsMut` auto-dereference if the inner type is a reference
+//! - `From<U> for T` implies `Into<T> for U`
+//! - `From` and `Into` are reflexive, which means that all types can `into()`
+//!   themselves and `from()` themselves
+//!
 //! See each trait for usage examples.
 
 #![stable(feature = "rust1", since = "1.0.0")]
@@ -30,6 +48,9 @@ use marker::Sized;
 ///
 /// [book]: ../../book/borrow-and-asref.html
 ///
+/// **Note: this trait must not fail**. If the conversion can fail, use a dedicated method which
+/// return an `Option<T>` or a `Result<T, E>`.
+///
 /// # Examples
 ///
 /// Both `String` and `&str` implement `AsRef<str>`:
@@ -45,6 +66,12 @@ use marker::Sized;
 /// let s = "hello".to_string();
 /// is_hello(s);
 /// ```
+///
+/// # Generic Impls
+///
+/// - `AsRef` auto-dereference if the inner type is a reference or a mutable
+/// reference (eg: `foo.as_ref()` will work the same if `foo` has type `&mut Foo` or `&&mut Foo`)
+///
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait AsRef<T: ?Sized> {
     /// Performs the conversion.
@@ -53,6 +80,15 @@ pub trait AsRef<T: ?Sized> {
 }
 
 /// A cheap, mutable reference-to-mutable reference conversion.
+///
+/// **Note: this trait must not fail**. If the conversion can fail, use a dedicated method which
+/// return an `Option<T>` or a `Result<T, E>`.
+///
+/// # Generic Impls
+///
+/// - `AsMut` auto-dereference if the inner type is a reference or a mutable
+/// reference (eg: `foo.as_ref()` will work the same if `foo` has type `&mut Foo` or `&&mut Foo`)
+///
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait AsMut<T: ?Sized> {
     /// Performs the conversion.
@@ -62,6 +98,13 @@ pub trait AsMut<T: ?Sized> {
 
 /// A conversion that consumes `self`, which may or may not be expensive.
 ///
+/// **Note: this trait must not fail**. If the conversion can fail, use a dedicated method which
+/// return an `Option<T>` or a `Result<T, E>`.
+///
+/// Library writer should not implement directly this trait, but should prefer the implementation
+/// of the `From` trait, which offer greater flexibility and provide the equivalent `Into`
+/// implementation for free, thanks to a blanket implementation in the standard library.
+///
 /// # Examples
 ///
 /// `String` implements `Into<Vec<u8>>`:
@@ -75,6 +118,12 @@ pub trait AsMut<T: ?Sized> {
 /// let s = "hello".to_string();
 /// is_hello(s);
 /// ```
+///
+/// # Generic Impls
+///
+/// - `From<T> for U` implies `Into<U> for T`
+/// - `into()` is reflexive, which means that `Into<T> for T` is implemented
+///
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait Into<T>: Sized {
     /// Performs the conversion.
@@ -84,6 +133,9 @@ pub trait Into<T>: Sized {
 
 /// Construct `Self` via a conversion.
 ///
+/// **Note: this trait must not fail**. If the conversion can fail, use a dedicated method which
+/// return an `Option<T>` or a `Result<T, E>`.
+///
 /// # Examples
 ///
 /// `String` implements `From<&str>`:
@@ -94,6 +146,11 @@ pub trait Into<T>: Sized {
 ///
 /// assert_eq!(string, other_string);
 /// ```
+/// # Generic impls
+///
+/// - `From<T> for U` implies `Into<U> for T`
+/// - `from()` is reflexive, which means that `From<T> for T` is implemented
+///
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait From<T>: Sized {
     /// Performs the conversion.