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.

Author: frewsxcv

src/liballoc/arc.rs

@@ -606,6 +606,7 @@ impl<T: fmt::Debug> fmt::Debug for Arc<T> {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: Default + Sync + Send> Default for Arc<T> {
+    /// Creates a new `Arc` using `Arc::new` with the `Default` value of `T`
     #[stable(feature = "rust1", since = "1.0.0")]
     fn default() -> Arc<T> { Arc::new(Default::default()) }
 }

src/liballoc/boxed.rs

@@ -150,12 +150,14 @@ pub unsafe fn into_raw<T : ?Sized>(b: Box<T>) -> *mut T {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: Default> Default for Box<T> {
+    /// Creates a new `Box<T>` by `box`ing the `Default` value of `T`
     #[stable(feature = "rust1", since = "1.0.0")]
     fn default() -> Box<T> { box Default::default() }
 }
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T> 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([]) }
 }

src/libcollections/binary_heap.rs

@@ -171,6 +171,7 @@ pub struct BinaryHeap<T> {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: Ord> Default for BinaryHeap<T> {
+    /// Creates a new `BinaryHeap` using `BinaryHeap::new`
     #[inline]
     fn default() -> BinaryHeap<T> { BinaryHeap::new() }
 }

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() }
 }

src/libcollections/btree/map.rs

@@ -863,6 +863,7 @@ impl<K: Hash, V: Hash> Hash for BTreeMap<K, V> {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<K: Ord, V> Default for BTreeMap<K, V> {
+    /// Creates a new `BTreeMap` using `BTreeMap::new`
     #[stable(feature = "rust1", since = "1.0.0")]
     fn default() -> BTreeMap<K, V> {
         BTreeMap::new()

src/libcollections/btree/set.rs

@@ -512,6 +512,7 @@ impl<T: Ord> Extend<T> for BTreeSet<T> {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: Ord> Default for BTreeSet<T> {
+    /// Creates a new `BTreeSet` using `BTreeSet::new`
     #[stable(feature = "rust1", since = "1.0.0")]
     fn default() -> BTreeSet<T> {
         BTreeSet::new()

src/libcollections/linked_list.rs

@@ -212,6 +212,7 @@ impl<T> LinkedList<T> {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T> Default for LinkedList<T> {
+    /// Creates a new `LinkedList` using `LinkedList::new`
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     fn default() -> LinkedList<T> { LinkedList::new() }

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 {

src/libcollections/vec.rs

@@ -1599,6 +1599,7 @@ impl<T> Drop for Vec<T> {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T> Default for Vec<T> {
+    /// Creates a new `Vec` using `Vec::new`
     #[stable(feature = "rust1", since = "1.0.0")]
     fn default() -> Vec<T> {
         Vec::new()

src/libcollections/vec_deque.rs

@@ -83,6 +83,7 @@ impl<T> Drop for VecDeque<T> {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T> Default for VecDeque<T> {
+    /// Creates a new `VecDeque` using `VecDeque::new`
     #[inline]
     fn default() -> VecDeque<T> { VecDeque::new() }
 }

src/libcollections/vec_map.rs

@@ -94,6 +94,7 @@ pub struct OccupiedEntry<'a, V:'a> {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<V> Default for VecMap<V> {
+    /// Creates a new `VecMap` using `VecMap::new`
     #[stable(feature = "rust1", since = "1.0.0")]
     #[inline]
     fn default() -> VecMap<V> { VecMap::new() }

src/libcore/cell.rs

@@ -244,6 +244,7 @@ impl<T:Copy> Clone for Cell<T> {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T:Default + Copy> Default for Cell<T> {
+    /// Creates a new `Cell` using `Cell::new` with the `Default` value of `T`
     #[stable(feature = "rust1", since = "1.0.0")]
     fn default() -> Cell<T> {
         Cell::new(Default::default())
@@ -482,6 +483,7 @@ impl<T: Clone> Clone for RefCell<T> {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T:Default> Default for RefCell<T> {
+    /// Creates a new `RefCell` using `RefCell::new` with the `Default` value of `T`
     #[stable(feature = "rust1", since = "1.0.0")]
     fn default() -> RefCell<T> {
         RefCell::new(Default::default())

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()
     }

src/libcore/option.rs

@@ -768,6 +768,7 @@ impl<T> AsSlice<T> for Option<T> {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T> Default for Option<T> {
+    /// Creates a new `Option` with value `None`
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     fn default() -> Option<T> { None }

src/libcore/slice.rs

@@ -622,6 +622,7 @@ impl<'a, T, U: ?Sized + AsSlice<T>> AsSlice<T> 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] { &[] }
 }

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 { "" }
 }

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,)+) {

src/libstd/collections/hash/map.rs

@@ -1235,6 +1235,7 @@ impl<K, V, S> Default for HashMap<K, V, S>
     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<K, V, S> {
         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()
     }

src/libstd/collections/hash/set.rs

@@ -640,6 +640,7 @@ impl<T, S> Default for HashSet<T, S>
     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<T, S> {
         HashSet::with_hash_state(Default::default())

src/libstd/collections/hash/state.rs

@@ -51,5 +51,6 @@ impl<H> Clone for DefaultState<H> {
 }
 
 impl<H> Default for DefaultState<H> {
+    /// Creates a new `DefaultState`
     fn default() -> DefaultState<H> { DefaultState(marker::PhantomData) }
 }

src/libsyntax/owned_slice.rs

@@ -65,6 +65,7 @@ impl<T> Deref for OwnedSlice<T> {
 }
 
 impl<T> Default for OwnedSlice<T> {
+    /// Creates a new `OwnedSlice` using `OwnedSlice::empty`
     fn default() -> OwnedSlice<T> {
         OwnedSlice::empty()
     }