Skip to content

Commit 1cc0ae4

Browse files
authored
Rollup merge of #89869 - kpreid:from-doc, r=yaahc
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. * The new documentation for construction of maps and sets from arrays of keys mentions the handling of duplicates. Future work could be to do this for *all* code paths that convert an iterable to a map or set. * 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.
2 parents 930fc4f + 6fd5cf5 commit 1cc0ae4

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
@@ -2052,6 +2052,8 @@ where
20522052

20532053
#[stable(feature = "std_collections_from_array", since = "1.56.0")]
20542054
impl<K: Ord, V, const N: usize> From<[(K, V); N]> for BTreeMap<K, V> {
2055+
/// Converts a `[(K, V); N]` into a `BTreeMap<(K, V)>`.
2056+
///
20552057
/// ```
20562058
/// use std::collections::BTreeMap;
20572059
///

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

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

10981098
#[stable(feature = "std_collections_from_array", since = "1.56.0")]
10991099
impl<T: Ord, const N: usize> From<[T; N]> for BTreeSet<T> {
1100+
/// Converts a `[T; N]` into a `BTreeSet<T>`.
1101+
///
11001102
/// ```
11011103
/// use std::collections::BTreeSet;
11021104
///

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
@@ -3049,6 +3049,8 @@ impl<T, A: Allocator> From<VecDeque<T, A>> for Vec<T, A> {
30493049

30503050
#[stable(feature = "std_collections_from_array", since = "1.56.0")]
30513051
impl<T, const N: usize> From<[T; N]> for VecDeque<T> {
3052+
/// Converts a `[T; N]` into a `VecDeque<T>`.
3053+
///
30523054
/// ```
30533055
/// use std::collections::VecDeque;
30543056
///

library/alloc/src/vec/mod.rs

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2906,17 +2906,18 @@ impl<T: Clone> From<&mut [T]> for Vec<T> {
29062906
#[cfg(not(no_global_oom_handling))]
29072907
#[stable(feature = "vec_from_array", since = "1.44.0")]
29082908
impl<T, const N: usize> From<[T; N]> for Vec<T> {
2909-
#[cfg(not(test))]
2910-
fn from(s: [T; N]) -> Vec<T> {
2911-
<[T]>::into_vec(box s)
2912-
}
29132909
/// Allocate a `Vec<T>` and move `s`'s items into it.
29142910
///
29152911
/// # Examples
29162912
///
29172913
/// ```
29182914
/// assert_eq!(Vec::from([1, 2, 3]), vec![1, 2, 3]);
29192915
/// ```
2916+
#[cfg(not(test))]
2917+
fn from(s: [T; N]) -> Vec<T> {
2918+
<[T]>::into_vec(box s)
2919+
}
2920+
29202921
#[cfg(test)]
29212922
fn from(s: [T; N]) -> Vec<T> {
29222923
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
}
@@ -1979,6 +1981,7 @@ impl<T: Default> Default for UnsafeCell<T> {
19791981
#[stable(feature = "cell_from", since = "1.12.0")]
19801982
#[rustc_const_unstable(feature = "const_convert", issue = "88674")]
19811983
impl<T> const From<T> for UnsafeCell<T> {
1984+
/// Creates a new `UnsafeCell<T>` containing the given value.
19821985
fn from(t: T) -> UnsafeCell<T> {
19831986
UnsafeCell::new(t)
19841987
}

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> const Into<U> for T
538538
where
539539
U: ~const 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
@@ -721,6 +721,9 @@ impl<T: ?Sized> const From<Unique<T>> for NonNull<T> {
721721
#[stable(feature = "nonnull", since = "1.25.0")]
722722
#[rustc_const_unstable(feature = "const_convert", issue = "88674")]
723723
impl<T: ?Sized> const From<&mut T> for NonNull<T> {
724+
/// Converts a `&mut T` to a `NonNull<T>`.
725+
///
726+
/// This conversion is safe and infallible since references cannot be null.
724727
#[inline]
725728
fn from(reference: &mut T) -> Self {
726729
// SAFETY: A mutable reference cannot be null.
@@ -731,6 +734,9 @@ impl<T: ?Sized> const From<&mut T> for NonNull<T> {
731734
#[stable(feature = "nonnull", since = "1.25.0")]
732735
#[rustc_const_unstable(feature = "const_convert", issue = "88674")]
733736
impl<T: ?Sized> const From<&T> for NonNull<T> {
737+
/// Converts a `&T` to a `NonNull<T>`.
738+
///
739+
/// This conversion is safe and infallible since references cannot be null.
734740
#[inline]
735741
fn from(reference: &T) -> Self {
736742
// 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)