Add from docs to all impls in lib std and core

Author: TimTheBig

library/alloc/src/bstr.rs

@@ -184,6 +184,10 @@ impl Default for ByteString {
 // #[cfg(not(test))] // https://github.com/rust-lang/rust/issues/135100
 // #[unstable(feature = "bstr", issue = "134915")]
 // impl<'a, const N: usize> From<&'a [u8; N]> for ByteString {
+//     /// Make a `ByteString` from a byte array ref.
+//     ///
+//     /// ## Cost
+//     /// Allocates a new `Vec`
 //     #[inline]
 //     fn from(s: &'a [u8; N]) -> Self {
 //         ByteString(s.as_slice().to_vec())
@@ -193,6 +197,10 @@ impl Default for ByteString {
 // #[cfg(not(test))] // https://github.com/rust-lang/rust/issues/135100
 // #[unstable(feature = "bstr", issue = "134915")]
 // impl<const N: usize> From<[u8; N]> for ByteString {
+//     /// Make a `ByteString` from a byte array.
+//     ///
+//     /// ## Cost
+//     /// Allocates a new `Vec`
 //     #[inline]
 //     fn from(s: [u8; N]) -> Self {
 //         ByteString(s.as_slice().to_vec())
@@ -202,6 +210,10 @@ impl Default for ByteString {
 // #[cfg(not(test))] // https://github.com/rust-lang/rust/issues/135100
 // #[unstable(feature = "bstr", issue = "134915")]
 // impl<'a> From<&'a [u8]> for ByteString {
+//     /// Make a `ByteString` from a byte slice.
+//     ///
+//     /// ## Cost
+//     /// Allocates a new `Vec`
 //     #[inline]
 //     fn from(s: &'a [u8]) -> Self {
 //         ByteString(s.to_vec())
@@ -210,6 +222,7 @@ impl Default for ByteString {
 //
 // #[unstable(feature = "bstr", issue = "134915")]
 // impl From<Vec<u8>> for ByteString {
+//     /// Make a `ByteString` with `Vec<u8>` as inner
 //     #[inline]
 //     fn from(s: Vec<u8>) -> Self {
 //         ByteString(s)
@@ -218,6 +231,7 @@ impl Default for ByteString {
 
 #[unstable(feature = "bstr", issue = "134915")]
 impl From<ByteString> for Vec<u8> {
+    /// Return the inner `Vec` of the byte string
     #[inline]
     fn from(s: ByteString) -> Self {
         s.0
@@ -229,6 +243,10 @@ impl From<ByteString> for Vec<u8> {
 // #[cfg(not(test))] // https://github.com/rust-lang/rust/issues/135100
 // #[unstable(feature = "bstr", issue = "134915")]
 // impl<'a> From<&'a str> for ByteString {
+//     /// Make a `ByteString` from a string slices bytes.
+//     ///
+//     /// ## Cost
+//     /// Allocates a new `Vec`
 //     #[inline]
 //     fn from(s: &'a str) -> Self {
 //         ByteString(s.as_bytes().to_vec())
@@ -237,6 +255,7 @@ impl From<ByteString> for Vec<u8> {
 //
 // #[unstable(feature = "bstr", issue = "134915")]
 // impl From<String> for ByteString {
+//     /// Create a `ByteString` from a `String`s bytes
 //     #[inline]
 //     fn from(s: String) -> Self {
 //         ByteString(s.into_bytes())
@@ -617,6 +636,7 @@ impl Clone for Box<ByteStr> {
 #[cfg(not(test))] // https://github.com/rust-lang/rust/issues/135100
 #[unstable(feature = "bstr", issue = "134915")]
 impl<'a> From<&'a ByteStr> for Cow<'a, ByteStr> {
+    /// Create a `Borrowed` cow from a `ByteStr`
     #[inline]
     fn from(s: &'a ByteStr) -> Self {
         Cow::Borrowed(s)
@@ -626,6 +646,7 @@ impl<'a> From<&'a ByteStr> for Cow<'a, ByteStr> {
 #[cfg(not(test))] // https://github.com/rust-lang/rust/issues/135100
 #[unstable(feature = "bstr", issue = "134915")]
 impl From<Box<[u8]>> for Box<ByteStr> {
+    /// Create a `Box<[u8]>` from `Box<ByteStr>`s raw
     #[inline]
     fn from(s: Box<[u8]>) -> Box<ByteStr> {
         // SAFETY: `ByteStr` is a transparent wrapper around `[u8]`.
@@ -636,6 +657,7 @@ impl From<Box<[u8]>> for Box<ByteStr> {
 #[cfg(not(test))] // https://github.com/rust-lang/rust/issues/135100
 #[unstable(feature = "bstr", issue = "134915")]
 impl From<Box<ByteStr>> for Box<[u8]> {
+    /// Create a `Box<ByteStr>` from `Box<[u8]>`s raw
     #[inline]
     fn from(s: Box<ByteStr>) -> Box<[u8]> {
         // SAFETY: `ByteStr` is a transparent wrapper around `[u8]`.
@@ -646,6 +668,7 @@ impl From<Box<ByteStr>> for Box<[u8]> {
 #[unstable(feature = "bstr", issue = "134915")]
 #[cfg(not(no_rc))]
 impl From<Rc<[u8]>> for Rc<ByteStr> {
+    /// Create a `Rc<[u8]>` from `Rc<ByteStr>`s raw
     #[inline]
     fn from(s: Rc<[u8]>) -> Rc<ByteStr> {
         // SAFETY: `ByteStr` is a transparent wrapper around `[u8]`.
@@ -656,6 +679,7 @@ impl From<Rc<[u8]>> for Rc<ByteStr> {
 #[unstable(feature = "bstr", issue = "134915")]
 #[cfg(not(no_rc))]
 impl From<Rc<ByteStr>> for Rc<[u8]> {
+    /// Create a `Rc<ByteStr>` from `Rc<[u8]>`s raw
     #[inline]
     fn from(s: Rc<ByteStr>) -> Rc<[u8]> {
         // SAFETY: `ByteStr` is a transparent wrapper around `[u8]`.
@@ -666,6 +690,7 @@ impl From<Rc<ByteStr>> for Rc<[u8]> {
 #[unstable(feature = "bstr", issue = "134915")]
 #[cfg(all(not(no_rc), not(no_sync), target_has_atomic = "ptr"))]
 impl From<Arc<[u8]>> for Arc<ByteStr> {
+    /// Create a `Arc<ByteStr>` from `Arc<[u8]>`s raw
     #[inline]
     fn from(s: Arc<[u8]>) -> Arc<ByteStr> {
         // SAFETY: `ByteStr` is a transparent wrapper around `[u8]`.
@@ -676,6 +701,7 @@ impl From<Arc<[u8]>> for Arc<ByteStr> {
 #[unstable(feature = "bstr", issue = "134915")]
 #[cfg(all(not(no_rc), not(no_sync), target_has_atomic = "ptr"))]
 impl From<Arc<ByteStr>> for Arc<[u8]> {
+    /// Create a `Arc<ByteStr>` from `Arc<[u8]>`s raw
     #[inline]
     fn from(s: Arc<ByteStr>) -> Arc<[u8]> {
         // SAFETY: `ByteStr` is a transparent wrapper around `[u8]`.
@@ -695,6 +721,10 @@ impl_partial_eq_ord_cow!(&'a ByteStr, Cow<'a, [u8]>);
 impl<'a> TryFrom<&'a ByteStr> for String {
     type Error = core::str::Utf8Error;
 
+    /// Convert `ByteStr`s bytes to a utf-8 `String`.
+    /// 
+    /// # Errors
+    /// If `ByteStr` is not valid utf-8
     #[inline]
     fn try_from(s: &'a ByteStr) -> Result<Self, Self::Error> {
         Ok(core::str::from_utf8(&s.0)?.into())

library/alloc/src/collections/mod.rs

@@ -109,6 +109,7 @@ pub enum TryReserveErrorKind {
     issue = "48043"
 )]
 impl From<TryReserveErrorKind> for TryReserveError {
+    /// Wrap kind in `TryReserveError`.
     #[inline]
     fn from(kind: TryReserveErrorKind) -> Self {
         Self { kind }

library/alloc/src/task.rs

@@ -109,6 +109,7 @@ pub trait Wake {
 impl<W: Wake + Send + Sync + 'static> From<Arc<W>> for Waker {
     /// Use a [`Wake`]-able type as a `Waker`.
     ///
+    /// ## Cost
     /// No heap allocations or atomic operations are used for this conversion.
     fn from(waker: Arc<W>) -> Waker {
         // SAFETY: This is safe because raw_waker safely constructs
@@ -121,6 +122,7 @@ impl<W: Wake + Send + Sync + 'static> From<Arc<W>> for Waker {
 impl<W: Wake + Send + Sync + 'static> From<Arc<W>> for RawWaker {
     /// Use a `Wake`-able type as a `RawWaker`.
     ///
+    /// ## Cost
     /// No heap allocations or atomic operations are used for this conversion.
     fn from(waker: Arc<W>) -> RawWaker {
         raw_waker(waker)
@@ -288,6 +290,7 @@ pub trait LocalWake {
 impl<W: LocalWake + 'static> From<Rc<W>> for LocalWaker {
     /// Use a `Wake`-able type as a `LocalWaker`.
     ///
+    /// ## Cost
     /// No heap allocations or atomic operations are used for this conversion.
     fn from(waker: Rc<W>) -> LocalWaker {
         // SAFETY: This is safe because raw_waker safely constructs
@@ -300,6 +303,7 @@ impl<W: LocalWake + 'static> From<Rc<W>> for LocalWaker {
 impl<W: LocalWake + 'static> From<Rc<W>> for RawWaker {
     /// Use a `Wake`-able type as a `RawWaker`.
     ///
+    /// ## Cost
     /// No heap allocations or atomic operations are used for this conversion.
     fn from(waker: Rc<W>) -> RawWaker {
         local_raw_waker(waker)

library/core/src/array/mod.rs

@@ -178,11 +178,24 @@ impl Error for TryFromSliceError {
 
 #[stable(feature = "try_from_slice_error", since = "1.36.0")]
 impl From<Infallible> for TryFromSliceError {
+    /// Match `Infallible` into `TryFromSliceError`.
     fn from(x: Infallible) -> TryFromSliceError {
         match x {}
     }
 }
 
+#[unstable(feature = "never_type", issue = "35121")]
+impl From<!> for TryFromSliceError {
+    /// Match `!` into `TryFromSliceError`.
+    #[inline]
+    fn from(never: !) -> TryFromSliceError {
+        // Match rather than coerce to make sure that code like
+        // `From<Infallible> for TryFromSliceError` above will keep working
+        // when `Infallible` becomes an alias to `!`.
+        match never {}
+    }
+}
+
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T, const N: usize> AsRef<[T]> for [T; N] {
     #[inline]

library/core/src/ascii/ascii_char.rs

@@ -546,6 +546,7 @@ macro_rules! into_int_impl {
         $(
             #[unstable(feature = "ascii_char", issue = "110998")]
             impl From<AsciiChar> for $ty {
+                #[doc = concat!("Convert `AsciiChar` as `u8` into `", stringify!($ty), "`")]
                 #[inline]
                 fn from(chr: AsciiChar) -> $ty {
                     chr as u8 as $ty

library/core/src/fmt/mod.rs

@@ -36,6 +36,7 @@ pub enum Alignment {
 #[doc(hidden)]
 #[unstable(feature = "fmt_internals", reason = "internal to standard library", issue = "none")]
 impl From<rt::Alignment> for Option<Alignment> {
+    /// Match the `Alignment` to the `Some` equivalent, `Unknown` matches `None`.
     fn from(value: rt::Alignment) -> Self {
         match value {
             rt::Alignment::Left => Some(Alignment::Left),

library/core/src/num/error.rs

@@ -27,13 +27,16 @@ impl Error for TryFromIntError {
 
 #[stable(feature = "try_from", since = "1.34.0")]
 impl From<Infallible> for TryFromIntError {
+    /// Match `Infallible` into `TryFromIntError`.
+    #[inline]
     fn from(x: Infallible) -> TryFromIntError {
         match x {}
     }
 }
 
 #[unstable(feature = "never_type", issue = "35121")]
 impl From<!> for TryFromIntError {
+    /// Match `!` into `TryFromIntError`.
     #[inline]
     fn from(never: !) -> TryFromIntError {
         // Match rather than coerce to make sure that code like

library/core/src/num/nonzero.rs

@@ -287,6 +287,7 @@ impl<T> From<NonZero<T>> for T
 where
     T: ZeroablePrimitive,
 {
+    /// Get the inner num of `NonZero`.
     #[inline]
     fn from(nonzero: NonZero<T>) -> Self {
         // Call `get` method to keep range information.

library/core/src/ptr/alignment.rs

@@ -189,6 +189,7 @@ impl TryFrom<usize> for Alignment {
 
 #[unstable(feature = "ptr_alignment_type", issue = "102070")]
 impl From<Alignment> for NonZero<usize> {
+    /// `Alignment` is non zero so the inner enum value is returned
     #[inline]
     fn from(align: Alignment) -> NonZero<usize> {
         align.as_nonzero()
@@ -197,6 +198,7 @@ impl From<Alignment> for NonZero<usize> {
 
 #[unstable(feature = "ptr_alignment_type", issue = "102070")]
 impl From<Alignment> for usize {
+    /// `Alignment` is unsined so the inner enum value is returned
     #[inline]
     fn from(align: Alignment) -> usize {
         align.as_usize()

library/core/src/range.rs

@@ -187,13 +187,15 @@ impl<T> IntoBounds<T> for Range<T> {
 
 #[unstable(feature = "new_range_api", issue = "125687")]
 impl<T> From<Range<T>> for legacy::Range<T> {
+    /// Make a new `legacy::Range` with the same start and end as `Range`
     #[inline]
     fn from(value: Range<T>) -> Self {
         Self { start: value.start, end: value.end }
     }
 }
 #[unstable(feature = "new_range_api", issue = "125687")]
 impl<T> From<legacy::Range<T>> for Range<T> {
+    /// Make a new `Range` with the same start and end as `legacy::Range`
     #[inline]
     fn from(value: legacy::Range<T>) -> Self {
         Self { start: value.start, end: value.end }
@@ -363,13 +365,15 @@ impl<T> IntoBounds<T> for RangeInclusive<T> {
 
 #[unstable(feature = "new_range_api", issue = "125687")]
 impl<T> From<RangeInclusive<T>> for legacy::RangeInclusive<T> {
+    /// Make a new `legacy::RangeInclusive` with the same start and end as `RangeInclusive`
     #[inline]
     fn from(value: RangeInclusive<T>) -> Self {
         Self::new(value.start, value.end)
     }
 }
 #[unstable(feature = "new_range_api", issue = "125687")]
 impl<T> From<legacy::RangeInclusive<T>> for RangeInclusive<T> {
+    /// Make a new `RangeInclusive` with the same start and end as `legacy::RangeInclusive`
     #[inline]
     fn from(value: legacy::RangeInclusive<T>) -> Self {
         assert!(
@@ -507,13 +511,15 @@ impl<T> IntoBounds<T> for RangeFrom<T> {
 
 #[unstable(feature = "new_range_api", issue = "125687")]
 impl<T> From<RangeFrom<T>> for legacy::RangeFrom<T> {
+    /// Make a new `legacy::RangeFrom` with the same start as `RangeFrom`
     #[inline]
     fn from(value: RangeFrom<T>) -> Self {
         Self { start: value.start }
     }
 }
 #[unstable(feature = "new_range_api", issue = "125687")]
 impl<T> From<legacy::RangeFrom<T>> for RangeFrom<T> {
+    /// Make a new `RangeFrom` with the same start as `legacy::RangeFrom`
     #[inline]
     fn from(value: legacy::RangeFrom<T>) -> Self {
         Self { start: value.start }