From 6fd5cf51c1528c16f8a186ced5d6d21b1d70e319 Mon Sep 17 00:00:00 2001 From: Kevin Reid Date: Wed, 13 Oct 2021 08:46:34 -0700 Subject: [PATCH] Add documentation to more `From::from` implementations. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit For users looking at documentation through IDE popups, this gives them relevant information rather than the generic trait documentation wording “Performs the conversion”. For users reading the documentation for a specific type for any reason, this informs them when the conversion may allocate or copy significant memory versus when it is always a move or cheap copy. Notes on specific cases: * The new documentation for `From for T` explains that it is not a conversion at all. * Also documented `impl Into for T where U: From`, the other central blanket implementation of conversion. * I did not add documentation to conversions of a specific error type to a more general error type. * I did not add documentation to unstable code. This change was prepared by searching for the text "From<... for" and so may have missed some cases that for whatever reason did not match. I also looked for `Into` impls but did not find any worth documenting by the above criteria. --- library/alloc/src/collections/btree/map.rs | 2 ++ library/alloc/src/collections/btree/set.rs | 2 ++ library/alloc/src/collections/linked_list.rs | 2 ++ library/alloc/src/collections/vec_deque/mod.rs | 2 ++ library/alloc/src/vec/mod.rs | 9 +++++---- library/core/src/cell.rs | 3 +++ library/core/src/convert/mod.rs | 5 +++++ library/core/src/lazy.rs | 1 + library/core/src/ptr/non_null.rs | 6 ++++++ library/core/src/ptr/unique.rs | 3 +++ library/core/src/sync/atomic.rs | 1 + library/core/src/task/poll.rs | 2 +- library/std/src/ffi/c_str.rs | 11 +++++++++++ library/std/src/ffi/os_str.rs | 12 ++++++++++++ library/std/src/path.rs | 6 +++--- library/std/src/process.rs | 8 ++++---- 16 files changed, 63 insertions(+), 12 deletions(-) diff --git a/library/alloc/src/collections/btree/map.rs b/library/alloc/src/collections/btree/map.rs index 2ff7b0fbb759c..f015e081ea3de 100644 --- a/library/alloc/src/collections/btree/map.rs +++ b/library/alloc/src/collections/btree/map.rs @@ -2047,6 +2047,8 @@ where #[stable(feature = "std_collections_from_array", since = "1.56.0")] impl From<[(K, V); N]> for BTreeMap { + /// Converts a `[(K, V); N]` into a `BTreeMap<(K, V)>`. + /// /// ``` /// use std::collections::BTreeMap; /// diff --git a/library/alloc/src/collections/btree/set.rs b/library/alloc/src/collections/btree/set.rs index 0322cabccde4b..ec4ed85437287 100644 --- a/library/alloc/src/collections/btree/set.rs +++ b/library/alloc/src/collections/btree/set.rs @@ -1092,6 +1092,8 @@ impl FromIterator for BTreeSet { #[stable(feature = "std_collections_from_array", since = "1.56.0")] impl From<[T; N]> for BTreeSet { + /// Converts a `[T; N]` into a `BTreeSet`. + /// /// ``` /// use std::collections::BTreeSet; /// diff --git a/library/alloc/src/collections/linked_list.rs b/library/alloc/src/collections/linked_list.rs index e4913b16adbe7..30b07c0aebe01 100644 --- a/library/alloc/src/collections/linked_list.rs +++ b/library/alloc/src/collections/linked_list.rs @@ -1953,6 +1953,8 @@ impl Hash for LinkedList { #[stable(feature = "std_collections_from_array", since = "1.56.0")] impl From<[T; N]> for LinkedList { + /// Converts a `[T; N]` into a `LinkedList`. + /// /// ``` /// use std::collections::LinkedList; /// diff --git a/library/alloc/src/collections/vec_deque/mod.rs b/library/alloc/src/collections/vec_deque/mod.rs index 00862615c3c7a..061e2758e4985 100644 --- a/library/alloc/src/collections/vec_deque/mod.rs +++ b/library/alloc/src/collections/vec_deque/mod.rs @@ -3018,6 +3018,8 @@ impl From> for Vec { #[stable(feature = "std_collections_from_array", since = "1.56.0")] impl From<[T; N]> for VecDeque { + /// Converts a `[T; N]` into a `VecDeque`. + /// /// ``` /// use std::collections::VecDeque; /// diff --git a/library/alloc/src/vec/mod.rs b/library/alloc/src/vec/mod.rs index 88bde6e8ce481..0cc4a55dc99c9 100644 --- a/library/alloc/src/vec/mod.rs +++ b/library/alloc/src/vec/mod.rs @@ -2908,10 +2908,6 @@ impl From<&mut [T]> for Vec { #[cfg(not(no_global_oom_handling))] #[stable(feature = "vec_from_array", since = "1.44.0")] impl From<[T; N]> for Vec { - #[cfg(not(test))] - fn from(s: [T; N]) -> Vec { - <[T]>::into_vec(box s) - } /// Allocate a `Vec` and move `s`'s items into it. /// /// # Examples @@ -2919,6 +2915,11 @@ impl From<[T; N]> for Vec { /// ``` /// assert_eq!(Vec::from([1, 2, 3]), vec![1, 2, 3]); /// ``` + #[cfg(not(test))] + fn from(s: [T; N]) -> Vec { + <[T]>::into_vec(box s) + } + #[cfg(test)] fn from(s: [T; N]) -> Vec { crate::slice::into_vec(box s) diff --git a/library/core/src/cell.rs b/library/core/src/cell.rs index 06dc5ecf2ffa6..235e43a3048d8 100644 --- a/library/core/src/cell.rs +++ b/library/core/src/cell.rs @@ -315,6 +315,7 @@ impl Ord for Cell { #[stable(feature = "cell_from", since = "1.12.0")] #[rustc_const_unstable(feature = "const_convert", issue = "88674")] impl const From for Cell { + /// Creates a new `Cell` containing the given value. fn from(t: T) -> Cell { Cell::new(t) } @@ -1244,6 +1245,7 @@ impl Ord for RefCell { #[stable(feature = "cell_from", since = "1.12.0")] #[rustc_const_unstable(feature = "const_convert", issue = "88674")] impl const From for RefCell { + /// Creates a new `RefCell` containing the given value. fn from(t: T) -> RefCell { RefCell::new(t) } @@ -1986,6 +1988,7 @@ impl Default for UnsafeCell { #[stable(feature = "cell_from", since = "1.12.0")] #[rustc_const_unstable(feature = "const_convert", issue = "88674")] impl const From for UnsafeCell { + /// Creates a new `UnsafeCell` containing the given value. fn from(t: T) -> UnsafeCell { UnsafeCell::new(t) } diff --git a/library/core/src/convert/mod.rs b/library/core/src/convert/mod.rs index 5aa53deee343d..de23dda1d0f4d 100644 --- a/library/core/src/convert/mod.rs +++ b/library/core/src/convert/mod.rs @@ -538,6 +538,10 @@ impl Into for T where U: From, { + /// Calls `U::from(self)`. + /// + /// That is, this conversion is whatever the implementation of + /// [From]<T> for U chooses to do. fn into(self) -> U { U::from(self) } @@ -547,6 +551,7 @@ where #[stable(feature = "rust1", since = "1.0.0")] #[rustc_const_unstable(feature = "const_convert", issue = "88674")] impl const From for T { + /// Returns the argument unchanged. fn from(t: T) -> T { t } diff --git a/library/core/src/lazy.rs b/library/core/src/lazy.rs index 2b8a5f3cbf345..6e08a7d24c6b0 100644 --- a/library/core/src/lazy.rs +++ b/library/core/src/lazy.rs @@ -75,6 +75,7 @@ impl Eq for OnceCell {} #[unstable(feature = "once_cell", issue = "74465")] impl const From for OnceCell { + /// Creates a new `OnceCell` which already contains the given `value`. fn from(value: T) -> Self { OnceCell { inner: UnsafeCell::new(Some(value)) } } diff --git a/library/core/src/ptr/non_null.rs b/library/core/src/ptr/non_null.rs index 58110b0680943..84ffd8bc8e204 100644 --- a/library/core/src/ptr/non_null.rs +++ b/library/core/src/ptr/non_null.rs @@ -714,6 +714,9 @@ impl const From> for NonNull { #[stable(feature = "nonnull", since = "1.25.0")] #[rustc_const_unstable(feature = "const_convert", issue = "88674")] impl const From<&mut T> for NonNull { + /// Converts a `&mut T` to a `NonNull`. + /// + /// This conversion is safe and infallible since references cannot be null. #[inline] fn from(reference: &mut T) -> Self { // SAFETY: A mutable reference cannot be null. @@ -724,6 +727,9 @@ impl const From<&mut T> for NonNull { #[stable(feature = "nonnull", since = "1.25.0")] #[rustc_const_unstable(feature = "const_convert", issue = "88674")] impl const From<&T> for NonNull { + /// Converts a `&T` to a `NonNull`. + /// + /// This conversion is safe and infallible since references cannot be null. #[inline] fn from(reference: &T) -> Self { // SAFETY: A reference cannot be null, so the conditions for diff --git a/library/core/src/ptr/unique.rs b/library/core/src/ptr/unique.rs index d650a6f974b97..f88d4b72fcf6b 100644 --- a/library/core/src/ptr/unique.rs +++ b/library/core/src/ptr/unique.rs @@ -178,6 +178,9 @@ impl fmt::Pointer for Unique { #[unstable(feature = "ptr_internals", issue = "none")] impl const From<&mut T> for Unique { + /// Converts a `&mut T` to a `Unique`. + /// + /// This conversion is infallible since references cannot be null. #[inline] fn from(reference: &mut T) -> Self { // SAFETY: A mutable reference cannot be null diff --git a/library/core/src/sync/atomic.rs b/library/core/src/sync/atomic.rs index 1dd3b2d8e3c8d..93cdab59e4429 100644 --- a/library/core/src/sync/atomic.rs +++ b/library/core/src/sync/atomic.rs @@ -1294,6 +1294,7 @@ impl const From for AtomicBool { #[stable(feature = "atomic_from", since = "1.23.0")] #[rustc_const_unstable(feature = "const_convert", issue = "88674")] impl const From<*mut T> for AtomicPtr { + /// Converts a `*mut T` into an `AtomicPtr`. #[inline] fn from(p: *mut T) -> Self { Self::new(p) diff --git a/library/core/src/task/poll.rs b/library/core/src/task/poll.rs index 72a030617ad8a..41f0a25dbc3e0 100644 --- a/library/core/src/task/poll.rs +++ b/library/core/src/task/poll.rs @@ -243,7 +243,7 @@ impl Poll>> { #[stable(feature = "futures_api", since = "1.36.0")] #[rustc_const_unstable(feature = "const_convert", issue = "88674")] impl const From for Poll { - /// Convert to a `Ready` variant. + /// Moves the value into a [`Poll::Ready`] to make a `Poll`. /// /// # Example /// diff --git a/library/std/src/ffi/c_str.rs b/library/std/src/ffi/c_str.rs index 465bbae8631c5..62b6eefbe1866 100644 --- a/library/std/src/ffi/c_str.rs +++ b/library/std/src/ffi/c_str.rs @@ -848,6 +848,8 @@ impl Borrow for CString { #[stable(feature = "cstring_from_cow_cstr", since = "1.28.0")] impl<'a> From> for CString { + /// Converts a `Cow<'a, CStr>` into a `CString`, by copying the contents if they are + /// borrowed. #[inline] fn from(s: Cow<'a, CStr>) -> Self { s.into_owned() @@ -856,6 +858,8 @@ impl<'a> From> for CString { #[stable(feature = "box_from_c_str", since = "1.17.0")] impl From<&CStr> for Box { + /// Converts a `&CStr` into a `Box`, + /// by copying the contents into a newly allocated [`Box`]. fn from(s: &CStr) -> Box { let boxed: Box<[u8]> = Box::from(s.to_bytes_with_nul()); unsafe { Box::from_raw(Box::into_raw(boxed) as *mut CStr) } @@ -864,6 +868,8 @@ impl From<&CStr> for Box { #[stable(feature = "box_from_cow", since = "1.45.0")] impl From> for Box { + /// Converts a `Cow<'a, CStr>` into a `Box`, + /// by copying the contents if they are borrowed. #[inline] fn from(cow: Cow<'_, CStr>) -> Box { match cow { @@ -960,6 +966,8 @@ impl From for Arc { #[stable(feature = "shared_from_slice2", since = "1.24.0")] impl From<&CStr> for Arc { + /// Converts a `&CStr` into a `Arc`, + /// by copying the contents into a newly allocated [`Arc`]. #[inline] fn from(s: &CStr) -> Arc { let arc: Arc<[u8]> = Arc::from(s.to_bytes_with_nul()); @@ -979,6 +987,8 @@ impl From for Rc { #[stable(feature = "shared_from_slice2", since = "1.24.0")] impl From<&CStr> for Rc { + /// Converts a `&CStr` into a `Rc`, + /// by copying the contents into a newly allocated [`Rc`]. #[inline] fn from(s: &CStr) -> Rc { let rc: Rc<[u8]> = Rc::from(s.to_bytes_with_nul()); @@ -1504,6 +1514,7 @@ impl ToOwned for CStr { #[stable(feature = "cstring_asref", since = "1.7.0")] impl From<&CStr> for CString { + /// Copies the contents of the `&CStr` into a newly allocated `CString`. fn from(s: &CStr) -> CString { s.to_owned() } diff --git a/library/std/src/ffi/os_str.rs b/library/std/src/ffi/os_str.rs index 0f9912fa64d8b..7bb2ff6770ec5 100644 --- a/library/std/src/ffi/os_str.rs +++ b/library/std/src/ffi/os_str.rs @@ -371,6 +371,8 @@ impl From for OsString { #[stable(feature = "rust1", since = "1.0.0")] impl> From<&T> for OsString { + /// Copies any value implementing [AsRef]<[OsStr]> + /// into a newly allocated [`OsString`]. fn from(s: &T) -> OsString { s.as_ref().to_os_string() } @@ -861,6 +863,7 @@ impl OsStr { #[stable(feature = "box_from_os_str", since = "1.17.0")] impl From<&OsStr> for Box { + /// Copies the string into a newly allocated [Box]<[OsStr]>. #[inline] fn from(s: &OsStr) -> Box { let rw = Box::into_raw(s.inner.into_box()) as *mut OsStr; @@ -870,6 +873,8 @@ impl From<&OsStr> for Box { #[stable(feature = "box_from_cow", since = "1.45.0")] impl From> for Box { + /// Converts a `Cow<'a, OsStr>` into a [Box]<[OsStr]>, + /// by copying the contents if they are borrowed. #[inline] fn from(cow: Cow<'_, OsStr>) -> Box { match cow { @@ -918,6 +923,7 @@ impl From for Arc { #[stable(feature = "shared_from_slice2", since = "1.24.0")] impl From<&OsStr> for Arc { + /// Copies the string into a newly allocated [Arc]<[OsStr]>. #[inline] fn from(s: &OsStr) -> Arc { let arc = s.inner.into_arc(); @@ -937,6 +943,7 @@ impl From for Rc { #[stable(feature = "shared_from_slice2", since = "1.24.0")] impl From<&OsStr> for Rc { + /// Copies the string into a newly allocated [Rc]<[OsStr]>. #[inline] fn from(s: &OsStr) -> Rc { let rc = s.inner.into_rc(); @@ -946,6 +953,7 @@ impl From<&OsStr> for Rc { #[stable(feature = "cow_from_osstr", since = "1.28.0")] impl<'a> From for Cow<'a, OsStr> { + /// Moves the string into a [`Cow::Owned`]. #[inline] fn from(s: OsString) -> Cow<'a, OsStr> { Cow::Owned(s) @@ -954,6 +962,7 @@ impl<'a> From for Cow<'a, OsStr> { #[stable(feature = "cow_from_osstr", since = "1.28.0")] impl<'a> From<&'a OsStr> for Cow<'a, OsStr> { + /// Converts the string reference into a [`Cow::Borrowed`]. #[inline] fn from(s: &'a OsStr) -> Cow<'a, OsStr> { Cow::Borrowed(s) @@ -962,6 +971,7 @@ impl<'a> From<&'a OsStr> for Cow<'a, OsStr> { #[stable(feature = "cow_from_osstr", since = "1.28.0")] impl<'a> From<&'a OsString> for Cow<'a, OsStr> { + /// Converts the string reference into a [`Cow::Borrowed`]. #[inline] fn from(s: &'a OsString) -> Cow<'a, OsStr> { Cow::Borrowed(s.as_os_str()) @@ -970,6 +980,8 @@ impl<'a> From<&'a OsString> for Cow<'a, OsStr> { #[stable(feature = "osstring_from_cow_osstr", since = "1.28.0")] impl<'a> From> for OsString { + /// Converts a `Cow<'a, OsStr>` into an [`OsString`], + /// by copying the contents if they are borrowed. #[inline] fn from(s: Cow<'a, OsStr>) -> Self { s.into_owned() diff --git a/library/std/src/path.rs b/library/std/src/path.rs index 9ade2847e8ea9..a4d0119c2a063 100644 --- a/library/std/src/path.rs +++ b/library/std/src/path.rs @@ -1581,7 +1581,7 @@ impl From> for Box { #[stable(feature = "path_buf_from_box", since = "1.18.0")] impl From> for PathBuf { - /// Converts a `Box` into a `PathBuf` + /// Converts a [Box]<[Path]> into a [`PathBuf`]. /// /// This conversion does not allocate or copy memory. #[inline] @@ -1592,7 +1592,7 @@ impl From> for PathBuf { #[stable(feature = "box_from_path_buf", since = "1.20.0")] impl From for Box { - /// Converts a `PathBuf` into a `Box` + /// Converts a [`PathBuf`] into a [Box]<[Path]>. /// /// This conversion currently should not allocate memory, /// but this behavior is not guaranteed on all platforms or in all future versions. @@ -1612,7 +1612,7 @@ impl Clone for Box { #[stable(feature = "rust1", since = "1.0.0")] impl> From<&T> for PathBuf { - /// Converts a borrowed `OsStr` to a `PathBuf`. + /// Converts a borrowed [`OsStr`] to a [`PathBuf`]. /// /// Allocates a [`PathBuf`] and copies the data into it. #[inline] diff --git a/library/std/src/process.rs b/library/std/src/process.rs index 4e9fd51f28229..ae39997de6212 100644 --- a/library/std/src/process.rs +++ b/library/std/src/process.rs @@ -1289,7 +1289,7 @@ impl fmt::Debug for Stdio { #[stable(feature = "stdio_from", since = "1.20.0")] impl From for Stdio { - /// Converts a `ChildStdin` into a `Stdio` + /// Converts a [`ChildStdin`] into a [`Stdio`]. /// /// # Examples /// @@ -1318,7 +1318,7 @@ impl From for Stdio { #[stable(feature = "stdio_from", since = "1.20.0")] impl From for Stdio { - /// Converts a `ChildStdout` into a `Stdio` + /// Converts a [`ChildStdout`] into a [`Stdio`]. /// /// # Examples /// @@ -1347,7 +1347,7 @@ impl From for Stdio { #[stable(feature = "stdio_from", since = "1.20.0")] impl From for Stdio { - /// Converts a `ChildStderr` into a `Stdio` + /// Converts a [`ChildStderr`] into a [`Stdio`]. /// /// # Examples /// @@ -1378,7 +1378,7 @@ impl From for Stdio { #[stable(feature = "stdio_from", since = "1.20.0")] impl From for Stdio { - /// Converts a `File` into a `Stdio` + /// Converts a [`File`](fs::File) into a [`Stdio`]. /// /// # Examples ///