Skip to content

Commit 6fd5cf5

Browse files
committed
Add documentation to more From::from implementations.
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<T> for T` explains that it is not a conversion at all. * Also documented `impl<T, U> Into<U> for T where U: From<T>`, 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.
1 parent 887999d commit 6fd5cf5

File tree

16 files changed

+63
-12
lines changed

16 files changed

+63
-12
lines changed

library/alloc/src/collections/btree/map.rs

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2047,6 +2047,8 @@ where
20472047

20482048
#[stable(feature = "std_collections_from_array", since = "1.56.0")]
20492049
impl<K: Ord, V, const N: usize> From<[(K, V); N]> for BTreeMap<K, V> {
2050+
/// Converts a `[(K, V); N]` into a `BTreeMap<(K, V)>`.
2051+
///
20502052
/// ```
20512053
/// use std::collections::BTreeMap;
20522054
///

library/alloc/src/collections/btree/set.rs

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1092,6 +1092,8 @@ impl<T: Ord> FromIterator<T> for BTreeSet<T> {
10921092

10931093
#[stable(feature = "std_collections_from_array", since = "1.56.0")]
10941094
impl<T: Ord, const N: usize> From<[T; N]> for BTreeSet<T> {
1095+
/// Converts a `[T; N]` into a `BTreeSet<T>`.
1096+
///
10951097
/// ```
10961098
/// use std::collections::BTreeSet;
10971099
///

library/alloc/src/collections/linked_list.rs

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1953,6 +1953,8 @@ impl<T: Hash> Hash for LinkedList<T> {
19531953

19541954
#[stable(feature = "std_collections_from_array", since = "1.56.0")]
19551955
impl<T, const N: usize> From<[T; N]> for LinkedList<T> {
1956+
/// Converts a `[T; N]` into a `LinkedList<T>`.
1957+
///
19561958
/// ```
19571959
/// use std::collections::LinkedList;
19581960
///

library/alloc/src/collections/vec_deque/mod.rs

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3018,6 +3018,8 @@ impl<T, A: Allocator> From<VecDeque<T, A>> for Vec<T, A> {
30183018

30193019
#[stable(feature = "std_collections_from_array", since = "1.56.0")]
30203020
impl<T, const N: usize> From<[T; N]> for VecDeque<T> {
3021+
/// Converts a `[T; N]` into a `VecDeque<T>`.
3022+
///
30213023
/// ```
30223024
/// use std::collections::VecDeque;
30233025
///

library/alloc/src/vec/mod.rs

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2908,17 +2908,18 @@ impl<T: Clone> From<&mut [T]> for Vec<T> {
29082908
#[cfg(not(no_global_oom_handling))]
29092909
#[stable(feature = "vec_from_array", since = "1.44.0")]
29102910
impl<T, const N: usize> From<[T; N]> for Vec<T> {
2911-
#[cfg(not(test))]
2912-
fn from(s: [T; N]) -> Vec<T> {
2913-
<[T]>::into_vec(box s)
2914-
}
29152911
/// Allocate a `Vec<T>` and move `s`'s items into it.
29162912
///
29172913
/// # Examples
29182914
///
29192915
/// ```
29202916
/// assert_eq!(Vec::from([1, 2, 3]), vec![1, 2, 3]);
29212917
/// ```
2918+
#[cfg(not(test))]
2919+
fn from(s: [T; N]) -> Vec<T> {
2920+
<[T]>::into_vec(box s)
2921+
}
2922+
29222923
#[cfg(test)]
29232924
fn from(s: [T; N]) -> Vec<T> {
29242925
crate::slice::into_vec(box s)

library/core/src/cell.rs

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -315,6 +315,7 @@ impl<T: Ord + Copy> Ord for Cell<T> {
315315
#[stable(feature = "cell_from", since = "1.12.0")]
316316
#[rustc_const_unstable(feature = "const_convert", issue = "88674")]
317317
impl<T> const From<T> for Cell<T> {
318+
/// Creates a new `Cell<T>` containing the given value.
318319
fn from(t: T) -> Cell<T> {
319320
Cell::new(t)
320321
}
@@ -1244,6 +1245,7 @@ impl<T: ?Sized + Ord> Ord for RefCell<T> {
12441245
#[stable(feature = "cell_from", since = "1.12.0")]
12451246
#[rustc_const_unstable(feature = "const_convert", issue = "88674")]
12461247
impl<T> const From<T> for RefCell<T> {
1248+
/// Creates a new `RefCell<T>` containing the given value.
12471249
fn from(t: T) -> RefCell<T> {
12481250
RefCell::new(t)
12491251
}
@@ -1986,6 +1988,7 @@ impl<T: Default> Default for UnsafeCell<T> {
19861988
#[stable(feature = "cell_from", since = "1.12.0")]
19871989
#[rustc_const_unstable(feature = "const_convert", issue = "88674")]
19881990
impl<T> const From<T> for UnsafeCell<T> {
1991+
/// Creates a new `UnsafeCell<T>` containing the given value.
19891992
fn from(t: T) -> UnsafeCell<T> {
19901993
UnsafeCell::new(t)
19911994
}

library/core/src/convert/mod.rs

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -538,6 +538,10 @@ impl<T, U> Into<U> for T
538538
where
539539
U: From<T>,
540540
{
541+
/// Calls `U::from(self)`.
542+
///
543+
/// That is, this conversion is whatever the implementation of
544+
/// <code>[From]&lt;T&gt; for U</code> chooses to do.
541545
fn into(self) -> U {
542546
U::from(self)
543547
}
@@ -547,6 +551,7 @@ where
547551
#[stable(feature = "rust1", since = "1.0.0")]
548552
#[rustc_const_unstable(feature = "const_convert", issue = "88674")]
549553
impl<T> const From<T> for T {
554+
/// Returns the argument unchanged.
550555
fn from(t: T) -> T {
551556
t
552557
}

library/core/src/lazy.rs

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,7 @@ impl<T: Eq> Eq for OnceCell<T> {}
7575

7676
#[unstable(feature = "once_cell", issue = "74465")]
7777
impl<T> const From<T> for OnceCell<T> {
78+
/// Creates a new `OnceCell<T>` which already contains the given `value`.
7879
fn from(value: T) -> Self {
7980
OnceCell { inner: UnsafeCell::new(Some(value)) }
8081
}

library/core/src/ptr/non_null.rs

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -714,6 +714,9 @@ impl<T: ?Sized> const From<Unique<T>> for NonNull<T> {
714714
#[stable(feature = "nonnull", since = "1.25.0")]
715715
#[rustc_const_unstable(feature = "const_convert", issue = "88674")]
716716
impl<T: ?Sized> const From<&mut T> for NonNull<T> {
717+
/// Converts a `&mut T` to a `NonNull<T>`.
718+
///
719+
/// This conversion is safe and infallible since references cannot be null.
717720
#[inline]
718721
fn from(reference: &mut T) -> Self {
719722
// SAFETY: A mutable reference cannot be null.
@@ -724,6 +727,9 @@ impl<T: ?Sized> const From<&mut T> for NonNull<T> {
724727
#[stable(feature = "nonnull", since = "1.25.0")]
725728
#[rustc_const_unstable(feature = "const_convert", issue = "88674")]
726729
impl<T: ?Sized> const From<&T> for NonNull<T> {
730+
/// Converts a `&T` to a `NonNull<T>`.
731+
///
732+
/// This conversion is safe and infallible since references cannot be null.
727733
#[inline]
728734
fn from(reference: &T) -> Self {
729735
// SAFETY: A reference cannot be null, so the conditions for

library/core/src/ptr/unique.rs

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -178,6 +178,9 @@ impl<T: ?Sized> fmt::Pointer for Unique<T> {
178178

179179
#[unstable(feature = "ptr_internals", issue = "none")]
180180
impl<T: ?Sized> const From<&mut T> for Unique<T> {
181+
/// Converts a `&mut T` to a `Unique<T>`.
182+
///
183+
/// This conversion is infallible since references cannot be null.
181184
#[inline]
182185
fn from(reference: &mut T) -> Self {
183186
// SAFETY: A mutable reference cannot be null

0 commit comments

Comments
 (0)