From 3f1192c37de9d0bdb4bec4d726b703fb7651685f Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Tue, 10 Mar 2015 23:51:53 -0400 Subject: [PATCH] Provide documentation for `Default` impls For the most part, the `Default` impls are pretty obvious as far as what we expect them to return, but I think it's better to explicitly state what's going to be returned in the documentation instead of relying on the user to make assumptions/look at the source. --- src/liballoc/arc.rs | 1 + src/liballoc/boxed.rs | 2 ++ src/libcollections/binary_heap.rs | 1 + src/libcollections/bit.rs | 2 ++ src/libcollections/btree/map.rs | 1 + src/libcollections/btree/set.rs | 1 + src/libcollections/linked_list.rs | 1 + src/libcollections/string.rs | 1 + src/libcollections/vec.rs | 1 + src/libcollections/vec_deque.rs | 1 + src/libcollections/vec_map.rs | 1 + src/libcore/cell.rs | 2 ++ src/libcore/hash/sip.rs | 1 + src/libcore/option.rs | 1 + src/libcore/slice.rs | 1 + src/libcore/str/mod.rs | 1 + src/libcore/tuple.rs | 2 ++ src/libstd/collections/hash/map.rs | 2 ++ src/libstd/collections/hash/set.rs | 1 + src/libstd/collections/hash/state.rs | 1 + src/libsyntax/owned_slice.rs | 1 + 21 files changed, 26 insertions(+) diff --git a/src/liballoc/arc.rs b/src/liballoc/arc.rs index dc1938cac1ada..f30820e2aa5f9 100644 --- a/src/liballoc/arc.rs +++ b/src/liballoc/arc.rs @@ -606,6 +606,7 @@ impl fmt::Debug for Arc { #[stable(feature = "rust1", since = "1.0.0")] impl Default for Arc { + /// Creates a new `Arc` using `Arc::new` with the `Default` value of `T` #[stable(feature = "rust1", since = "1.0.0")] fn default() -> Arc { Arc::new(Default::default()) } } diff --git a/src/liballoc/boxed.rs b/src/liballoc/boxed.rs index 9351b11010030..a666c26bb4ea2 100644 --- a/src/liballoc/boxed.rs +++ b/src/liballoc/boxed.rs @@ -150,12 +150,14 @@ pub unsafe fn into_raw(b: Box) -> *mut T { #[stable(feature = "rust1", since = "1.0.0")] impl Default for Box { + /// Creates a new `Box` by `box`ing the `Default` value of `T` #[stable(feature = "rust1", since = "1.0.0")] fn default() -> Box { box Default::default() } } #[stable(feature = "rust1", since = "1.0.0")] impl Default for Box<[T]> { + /// Creates a new `Box<[T]>` by `box`ing an empty slice #[stable(feature = "rust1", since = "1.0.0")] fn default() -> Box<[T]> { Box::<[T; 0]>::new([]) } } diff --git a/src/libcollections/binary_heap.rs b/src/libcollections/binary_heap.rs index 2e575ddb00a32..420b559eb205f 100644 --- a/src/libcollections/binary_heap.rs +++ b/src/libcollections/binary_heap.rs @@ -171,6 +171,7 @@ pub struct BinaryHeap { #[stable(feature = "rust1", since = "1.0.0")] impl Default for BinaryHeap { + /// Creates a new `BinaryHeap` using `BinaryHeap::new` #[inline] fn default() -> BinaryHeap { BinaryHeap::new() } } diff --git a/src/libcollections/bit.rs b/src/libcollections/bit.rs index 7524fb6cf18a6..20b5a76a30694 100644 --- a/src/libcollections/bit.rs +++ b/src/libcollections/bit.rs @@ -918,6 +918,7 @@ impl BitVec { #[stable(feature = "rust1", since = "1.0.0")] impl Default for BitVec { + /// Creates a new `BitVec` using `BitVec::new` #[inline] fn default() -> BitVec { BitVec::new() } } @@ -1128,6 +1129,7 @@ pub struct BitSet { #[stable(feature = "rust1", since = "1.0.0")] impl Default for BitSet { + /// Creates a new `BitSet` using `BitSet::new` #[inline] fn default() -> BitSet { BitSet::new() } } diff --git a/src/libcollections/btree/map.rs b/src/libcollections/btree/map.rs index 1fa592ac477a2..de4c6bd3d4e49 100644 --- a/src/libcollections/btree/map.rs +++ b/src/libcollections/btree/map.rs @@ -863,6 +863,7 @@ impl Hash for BTreeMap { #[stable(feature = "rust1", since = "1.0.0")] impl Default for BTreeMap { + /// Creates a new `BTreeMap` using `BTreeMap::new` #[stable(feature = "rust1", since = "1.0.0")] fn default() -> BTreeMap { BTreeMap::new() diff --git a/src/libcollections/btree/set.rs b/src/libcollections/btree/set.rs index bc2e68b999a55..11594097c16c1 100644 --- a/src/libcollections/btree/set.rs +++ b/src/libcollections/btree/set.rs @@ -512,6 +512,7 @@ impl Extend for BTreeSet { #[stable(feature = "rust1", since = "1.0.0")] impl Default for BTreeSet { + /// Creates a new `BTreeSet` using `BTreeSet::new` #[stable(feature = "rust1", since = "1.0.0")] fn default() -> BTreeSet { BTreeSet::new() diff --git a/src/libcollections/linked_list.rs b/src/libcollections/linked_list.rs index 5ca3cb380583b..45f54ec92f401 100644 --- a/src/libcollections/linked_list.rs +++ b/src/libcollections/linked_list.rs @@ -212,6 +212,7 @@ impl LinkedList { #[stable(feature = "rust1", since = "1.0.0")] impl Default for LinkedList { + /// Creates a new `LinkedList` using `LinkedList::new` #[inline] #[stable(feature = "rust1", since = "1.0.0")] fn default() -> LinkedList { LinkedList::new() } diff --git a/src/libcollections/string.rs b/src/libcollections/string.rs index 83c63e47e506b..e40e29e13db3d 100644 --- a/src/libcollections/string.rs +++ b/src/libcollections/string.rs @@ -811,6 +811,7 @@ impl Str for String { #[stable(feature = "rust1", since = "1.0.0")] impl Default for String { + /// Creates a new `String` using `String::new` #[inline] #[stable(feature = "rust1", since = "1.0.0")] fn default() -> String { diff --git a/src/libcollections/vec.rs b/src/libcollections/vec.rs index ca0092a6e66dd..a3960211d35b7 100644 --- a/src/libcollections/vec.rs +++ b/src/libcollections/vec.rs @@ -1599,6 +1599,7 @@ impl Drop for Vec { #[stable(feature = "rust1", since = "1.0.0")] impl Default for Vec { + /// Creates a new `Vec` using `Vec::new` #[stable(feature = "rust1", since = "1.0.0")] fn default() -> Vec { Vec::new() diff --git a/src/libcollections/vec_deque.rs b/src/libcollections/vec_deque.rs index cab589d55beae..e2c4f5b81743c 100644 --- a/src/libcollections/vec_deque.rs +++ b/src/libcollections/vec_deque.rs @@ -83,6 +83,7 @@ impl Drop for VecDeque { #[stable(feature = "rust1", since = "1.0.0")] impl Default for VecDeque { + /// Creates a new `VecDeque` using `VecDeque::new` #[inline] fn default() -> VecDeque { VecDeque::new() } } diff --git a/src/libcollections/vec_map.rs b/src/libcollections/vec_map.rs index 431c8d5df8c0a..630b69407d41f 100644 --- a/src/libcollections/vec_map.rs +++ b/src/libcollections/vec_map.rs @@ -94,6 +94,7 @@ pub struct OccupiedEntry<'a, V:'a> { #[stable(feature = "rust1", since = "1.0.0")] impl Default for VecMap { + /// Creates a new `VecMap` using `VecMap::new` #[stable(feature = "rust1", since = "1.0.0")] #[inline] fn default() -> VecMap { VecMap::new() } diff --git a/src/libcore/cell.rs b/src/libcore/cell.rs index 4f77a20c7cac8..8d99b2de9d73f 100644 --- a/src/libcore/cell.rs +++ b/src/libcore/cell.rs @@ -244,6 +244,7 @@ impl Clone for Cell { #[stable(feature = "rust1", since = "1.0.0")] impl Default for Cell { + /// Creates a new `Cell` using `Cell::new` with the `Default` value of `T` #[stable(feature = "rust1", since = "1.0.0")] fn default() -> Cell { Cell::new(Default::default()) @@ -482,6 +483,7 @@ impl Clone for RefCell { #[stable(feature = "rust1", since = "1.0.0")] impl Default for RefCell { + /// Creates a new `RefCell` using `RefCell::new` with the `Default` value of `T` #[stable(feature = "rust1", since = "1.0.0")] fn default() -> RefCell { RefCell::new(Default::default()) diff --git a/src/libcore/hash/sip.rs b/src/libcore/hash/sip.rs index bd1516e0cfcc8..ff3f33c99cf7d 100644 --- a/src/libcore/hash/sip.rs +++ b/src/libcore/hash/sip.rs @@ -223,6 +223,7 @@ impl Clone for SipHasher { #[stable(feature = "rust1", since = "1.0.0")] impl Default for SipHasher { + /// Creates a new `SipHasher` using `SipHasher::new` fn default() -> SipHasher { SipHasher::new() } diff --git a/src/libcore/option.rs b/src/libcore/option.rs index 5343cdaaf088c..2718ef45bf750 100644 --- a/src/libcore/option.rs +++ b/src/libcore/option.rs @@ -768,6 +768,7 @@ impl AsSlice for Option { #[stable(feature = "rust1", since = "1.0.0")] impl Default for Option { + /// Creates a new `Option` with value `None` #[inline] #[stable(feature = "rust1", since = "1.0.0")] fn default() -> Option { None } diff --git a/src/libcore/slice.rs b/src/libcore/slice.rs index 1f58d7753549d..4961ff1227909 100644 --- a/src/libcore/slice.rs +++ b/src/libcore/slice.rs @@ -622,6 +622,7 @@ impl<'a, T, U: ?Sized + AsSlice> AsSlice for &'a mut U { #[stable(feature = "rust1", since = "1.0.0")] impl<'a, T> Default for &'a [T] { + /// Creates a new empty slice #[stable(feature = "rust1", since = "1.0.0")] fn default() -> &'a [T] { &[] } } diff --git a/src/libcore/str/mod.rs b/src/libcore/str/mod.rs index 4e8a56fbefb25..ef938eaac5e91 100644 --- a/src/libcore/str/mod.rs +++ b/src/libcore/str/mod.rs @@ -1702,6 +1702,7 @@ pub fn char_range_at_raw(bytes: &[u8], i: usize) -> (u32, usize) { #[stable(feature = "rust1", since = "1.0.0")] impl<'a> Default for &'a str { + /// Creates a new empty string slice #[stable(feature = "rust1", since = "1.0.0")] fn default() -> &'a str { "" } } diff --git a/src/libcore/tuple.rs b/src/libcore/tuple.rs index 72b2d5dc18882..98e8af040c147 100644 --- a/src/libcore/tuple.rs +++ b/src/libcore/tuple.rs @@ -112,6 +112,8 @@ macro_rules! tuple_impls { #[stable(feature = "rust1", since = "1.0.0")] impl<$($T:Default),+> Default for ($($T,)+) { + /// Creates a new tuple containing the `Default` value for each of the type + /// parameters #[stable(feature = "rust1", since = "1.0.0")] #[inline] fn default() -> ($($T,)+) { diff --git a/src/libstd/collections/hash/map.rs b/src/libstd/collections/hash/map.rs index 9502302aa53ab..3e40fd33f7ff7 100644 --- a/src/libstd/collections/hash/map.rs +++ b/src/libstd/collections/hash/map.rs @@ -1235,6 +1235,7 @@ impl Default for HashMap where K: Eq + Hash, S: HashState + Default, { + /// Creates a new `HashMap` using `HashMap::with_hash_state` with the `Default` value for `S` fn default() -> HashMap { HashMap::with_hash_state(Default::default()) } @@ -1600,6 +1601,7 @@ impl HashState for RandomState { reason = "hashing an hash maps may be altered")] impl Default for RandomState { #[inline] + /// Creates a new `RandomState` using `RandomState::new` fn default() -> RandomState { RandomState::new() } diff --git a/src/libstd/collections/hash/set.rs b/src/libstd/collections/hash/set.rs index cdc0ebd76aada..d8338ade4613a 100644 --- a/src/libstd/collections/hash/set.rs +++ b/src/libstd/collections/hash/set.rs @@ -640,6 +640,7 @@ impl Default for HashSet where T: Eq + Hash, S: HashState + Default, { + /// Creates a new `HashSet` using `HashSet::with_hash_state` with the `Default` value for `S` #[stable(feature = "rust1", since = "1.0.0")] fn default() -> HashSet { HashSet::with_hash_state(Default::default()) diff --git a/src/libstd/collections/hash/state.rs b/src/libstd/collections/hash/state.rs index 3a06d2d03bf3f..5e02f29d8e756 100644 --- a/src/libstd/collections/hash/state.rs +++ b/src/libstd/collections/hash/state.rs @@ -51,5 +51,6 @@ impl Clone for DefaultState { } impl Default for DefaultState { + /// Creates a new `DefaultState` fn default() -> DefaultState { DefaultState(marker::PhantomData) } } diff --git a/src/libsyntax/owned_slice.rs b/src/libsyntax/owned_slice.rs index 25f1f9b8480a1..5ca3d32571ba7 100644 --- a/src/libsyntax/owned_slice.rs +++ b/src/libsyntax/owned_slice.rs @@ -65,6 +65,7 @@ impl Deref for OwnedSlice { } impl Default for OwnedSlice { + /// Creates a new `OwnedSlice` using `OwnedSlice::empty` fn default() -> OwnedSlice { OwnedSlice::empty() }