Rollup merge of #36396 - athulappadan:Default-docs, r=bluss

Documentation of what Default does for each type

Addresses #36265
I haven't changed the following types due to doubts:

1)src/libstd/ffi/c_str.rs
2)src/libcore/iter/sources.rs
3)src/libcore/hash/mod.rs
4)src/libcore/hash/mod.rs
5)src/librustc/middle/privacy.rs

r? @steveklabnik

30 files changed, 38 insertions, 0 deletions

diff --git a/src/liballoc/arc.rs b/src/liballoc/arc.rs
index b54b71cabd1..3d579641b96 100644
--- a/src/liballoc/arc.rs
+++ b/src/liballoc/arc.rs
@@ -718,6 +718,7 @@ impl<T: ?Sized> Clone for Weak<T> {
 
 #[stable(feature = "downgraded_weak", since = "1.10.0")]
 impl<T> Default for Weak<T> {
+    /// Constructs a new `Weak<T>` without an accompanying instance of T.
     fn default() -> Weak<T> {
         Weak::new()
     }
@@ -923,6 +924,7 @@ impl<T: ?Sized> fmt::Pointer for Arc<T> {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: Default> Default for Arc<T> {
+    /// Creates a new `Arc<T>`, with the `Default` value for T.
     fn default() -> Arc<T> {
         Arc::new(Default::default())
     }
diff --git a/src/liballoc/boxed.rs b/src/liballoc/boxed.rs
index 70c429cc360..bc9b6e805ef 100644
--- a/src/liballoc/boxed.rs
+++ b/src/liballoc/boxed.rs
@@ -290,6 +290,7 @@ impl<T: ?Sized> Box<T> {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: Default> Default for Box<T> {
+    /// Creates a `Box<T>`, with the `Default` value for T.
     fn default() -> Box<T> {
         box Default::default()
     }
diff --git a/src/liballoc/rc.rs b/src/liballoc/rc.rs
index c24c7ca47ad..dadddbc2cb3 100644
--- a/src/liballoc/rc.rs
+++ b/src/liballoc/rc.rs
@@ -870,6 +870,7 @@ impl<T: ?Sized + fmt::Debug> fmt::Debug for Weak<T> {
 
 #[stable(feature = "downgraded_weak", since = "1.10.0")]
 impl<T> Default for Weak<T> {
+    /// Creates a new `Weak<T>`.
     fn default() -> Weak<T> {
         Weak::new()
     }
diff --git a/src/libcollections/binary_heap.rs b/src/libcollections/binary_heap.rs
index 0b923468c74..1fe921543bd 100644
--- a/src/libcollections/binary_heap.rs
+++ b/src/libcollections/binary_heap.rs
@@ -263,6 +263,7 @@ impl<T: Clone> Clone for BinaryHeap<T> {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: Ord> Default for BinaryHeap<T> {
+    /// Creates an empty `BinaryHeap<T>`.
     #[inline]
     fn default() -> BinaryHeap<T> {
         BinaryHeap::new()
diff --git a/src/libcollections/borrow.rs b/src/libcollections/borrow.rs
index 3ad1d082985..700f88dc0f2 100644
--- a/src/libcollections/borrow.rs
+++ b/src/libcollections/borrow.rs
@@ -249,6 +249,7 @@ impl<'a, B: ?Sized> Default for Cow<'a, B>
     where B: ToOwned,
           <B as ToOwned>::Owned: Default
 {
+    /// Creates an owned Cow<'a, B> with the default value for the contained owned value.
     fn default() -> Cow<'a, B> {
         Owned(<B as ToOwned>::Owned::default())
     }
diff --git a/src/libcollections/btree/map.rs b/src/libcollections/btree/map.rs
index 624083a8eaf..36cb5a1fd9f 100644
--- a/src/libcollections/btree/map.rs
+++ b/src/libcollections/btree/map.rs
@@ -1667,6 +1667,7 @@ impl<K: Hash, V: Hash> Hash for BTreeMap<K, V> {
 }
 
 impl<K: Ord, V> Default for BTreeMap<K, V> {
+    /// Creates an empty `BTreeMap<K, V>`.
     fn default() -> BTreeMap<K, V> {
         BTreeMap::new()
     }
diff --git a/src/libcollections/btree/set.rs b/src/libcollections/btree/set.rs
index 5d7b00f57c8..fc2a7f82547 100644
--- a/src/libcollections/btree/set.rs
+++ b/src/libcollections/btree/set.rs
@@ -674,6 +674,7 @@ impl<'a, T: 'a + Ord + Copy> Extend<&'a T> for BTreeSet<T> {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: Ord> Default for BTreeSet<T> {
+    /// Makes an empty `BTreeSet<T>` with a reasonable choice of B.
     fn default() -> BTreeSet<T> {
         BTreeSet::new()
     }
diff --git a/src/libcollections/linked_list.rs b/src/libcollections/linked_list.rs
index 769c5162a45..690c4f4af35 100644
--- a/src/libcollections/linked_list.rs
+++ b/src/libcollections/linked_list.rs
@@ -164,6 +164,7 @@ impl<T> LinkedList<T> {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T> Default for LinkedList<T> {
+    /// Creates an empty `LinkedList<T>`.
     #[inline]
     fn default() -> Self {
         Self::new()
diff --git a/src/libcollections/string.rs b/src/libcollections/string.rs
index 3a304c62929..773e94f1b41 100644
--- a/src/libcollections/string.rs
+++ b/src/libcollections/string.rs
@@ -1567,6 +1567,7 @@ impl_eq! { Cow<'a, str>, String }
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl Default for String {
+    /// Creates an empty `String`.
     #[inline]
     fn default() -> String {
         String::new()
diff --git a/src/libcollections/vec.rs b/src/libcollections/vec.rs
index 7388e883434..f8b4a92df2c 100644
--- a/src/libcollections/vec.rs
+++ b/src/libcollections/vec.rs
@@ -1652,6 +1652,7 @@ impl<T> Drop for Vec<T> {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T> Default for Vec<T> {
+    /// Creates an empty `Vec<T>`.
     fn default() -> Vec<T> {
         Vec::new()
     }
diff --git a/src/libcollections/vec_deque.rs b/src/libcollections/vec_deque.rs
index 96624f121b2..2e561dabb47 100644
--- a/src/libcollections/vec_deque.rs
+++ b/src/libcollections/vec_deque.rs
@@ -84,6 +84,7 @@ impl<T> Drop for VecDeque<T> {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T> Default for VecDeque<T> {
+    /// Creates an empty `VecDeque<T>`.
     #[inline]
     fn default() -> VecDeque<T> {
         VecDeque::new()
diff --git a/src/libcore/cell.rs b/src/libcore/cell.rs
index f0710a1d935..51221f1b9b9 100644
--- a/src/libcore/cell.rs
+++ b/src/libcore/cell.rs
@@ -317,6 +317,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 `Cell<T>`, with the `Default` value for T.
     #[inline]
     fn default() -> Cell<T> {
         Cell::new(Default::default())
@@ -758,6 +759,7 @@ impl<T: Clone> Clone for RefCell<T> {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T:Default> Default for RefCell<T> {
+    /// Creates a `RefCell<T>`, with the `Default` value for T.
     #[inline]
     fn default() -> RefCell<T> {
         RefCell::new(Default::default())
@@ -1139,6 +1141,7 @@ impl<T: ?Sized> UnsafeCell<T> {
 
 #[stable(feature = "unsafe_cell_default", since = "1.9.0")]
 impl<T: Default> Default for UnsafeCell<T> {
+    /// Creates an `UnsafeCell`, with the `Default` value for T.
     fn default() -> UnsafeCell<T> {
         UnsafeCell::new(Default::default())
     }
diff --git a/src/libcore/hash/sip.rs b/src/libcore/hash/sip.rs
index bd6cae92b05..dc53683d633 100644
--- a/src/libcore/hash/sip.rs
+++ b/src/libcore/hash/sip.rs
@@ -333,6 +333,7 @@ impl<S: Sip> Clone for Hasher<S> {
 }
 
 impl<S: Sip> Default for Hasher<S> {
+    /// Creates a `Hasher<S>` with the two initial keys set to 0.
     #[inline]
     fn default() -> Hasher<S> {
         Hasher::new_with_keys(0, 0)
diff --git a/src/libcore/option.rs b/src/libcore/option.rs
index dacb396ee40..b9fb2dc90c7 100644
--- a/src/libcore/option.rs
+++ b/src/libcore/option.rs
@@ -714,6 +714,7 @@ fn expect_failed(msg: &str) -> ! {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T> Default for Option<T> {
+    /// Returns None.
     #[inline]
     fn default() -> Option<T> { None }
 }
diff --git a/src/libcore/slice.rs b/src/libcore/slice.rs
index b22bdb43414..7b147faccd2 100644
--- a/src/libcore/slice.rs
+++ b/src/libcore/slice.rs
@@ -755,11 +755,13 @@ impl<T> ops::IndexMut<ops::RangeToInclusive<usize>> for [T] {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<'a, T> Default for &'a [T] {
+    /// Creates an empty slice.
     fn default() -> &'a [T] { &[] }
 }
 
 #[stable(feature = "mut_slice_default", since = "1.5.0")]
 impl<'a, T> Default for &'a mut [T] {
+    /// Creates a mutable empty slice.
     fn default() -> &'a mut [T] { &mut [] }
 }
 
diff --git a/src/libcore/str/mod.rs b/src/libcore/str/mod.rs
index 18e43c02c64..1f1ae6f12ab 100644
--- a/src/libcore/str/mod.rs
+++ b/src/libcore/str/mod.rs
@@ -1987,5 +1987,6 @@ impl AsRef<[u8]> for str {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<'a> Default for &'a str {
+    /// Creates an empty str
     fn default() -> &'a str { "" }
 }
diff --git a/src/libcore/sync/atomic.rs b/src/libcore/sync/atomic.rs
index 75ddd2021a8..f5f37be52de 100644
--- a/src/libcore/sync/atomic.rs
+++ b/src/libcore/sync/atomic.rs
@@ -95,6 +95,7 @@ pub struct AtomicBool {
 #[cfg(target_has_atomic = "8")]
 #[stable(feature = "rust1", since = "1.0.0")]
 impl Default for AtomicBool {
+    /// Creates an `AtomicBool` initialised as false.
     fn default() -> Self {
         Self::new(false)
     }
@@ -117,6 +118,7 @@ pub struct AtomicPtr<T> {
 #[cfg(target_has_atomic = "ptr")]
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T> Default for AtomicPtr<T> {
+    /// Creates a null `AtomicPtr<T>`.
     fn default() -> AtomicPtr<T> {
         AtomicPtr::new(::ptr::null_mut())
     }
diff --git a/src/librand/reseeding.rs b/src/librand/reseeding.rs
index c7d560eb1f8..48395c12faf 100644
--- a/src/librand/reseeding.rs
+++ b/src/librand/reseeding.rs
@@ -113,6 +113,7 @@ impl<R: Rng + Default> Reseeder<R> for ReseedWithDefault {
 }
 #[stable(feature = "rust1", since = "1.0.0")]
 impl Default for ReseedWithDefault {
+    /// Creates an instance of `ReseedWithDefault`.
     fn default() -> ReseedWithDefault {
         ReseedWithDefault
     }
@@ -137,6 +138,7 @@ mod tests {
         }
     }
     impl Default for Counter {
+    /// Constructs a `Counter` with initial value zero.
         fn default() -> Counter {
             Counter { i: 0 }
         }
diff --git a/src/librustc/ty/layout.rs b/src/librustc/ty/layout.rs
index e3f3da916a0..6fec698cfac 100644
--- a/src/librustc/ty/layout.rs
+++ b/src/librustc/ty/layout.rs
@@ -45,6 +45,7 @@ pub struct TargetDataLayout {
 }
 
 impl Default for TargetDataLayout {
+    /// Creates an instance of `TargetDataLayout`.
     fn default() -> TargetDataLayout {
         TargetDataLayout {
             endian: Endian::Big,
diff --git a/src/librustc_data_structures/fnv.rs b/src/librustc_data_structures/fnv.rs
index 47f623266f3..ae90c2fac83 100644
--- a/src/librustc_data_structures/fnv.rs
+++ b/src/librustc_data_structures/fnv.rs
@@ -35,6 +35,7 @@ pub fn FnvHashSet<V: Hash + Eq>() -> FnvHashSet<V> {
 pub struct FnvHasher(u64);
 
 impl Default for FnvHasher {
+    /// Creates a `FnvHasher`, with a 64-bit hex initial value.
     #[inline]
     fn default() -> FnvHasher {
         FnvHasher(0xcbf29ce484222325)
diff --git a/src/librustc_resolve/resolve_imports.rs b/src/librustc_resolve/resolve_imports.rs
index 74f88433b35..29add1f9b9d 100644
--- a/src/librustc_resolve/resolve_imports.rs
+++ b/src/librustc_resolve/resolve_imports.rs
@@ -109,6 +109,7 @@ enum SingleImports<'a> {
 }
 
 impl<'a> Default for SingleImports<'a> {
+    /// Creates a `SingleImports<'a>` of None type.
     fn default() -> Self {
         SingleImports::None
     }
diff --git a/src/libstd/collections/hash/map.rs b/src/libstd/collections/hash/map.rs
index 4eb2c8f0644..eb1653f18cb 100644
--- a/src/libstd/collections/hash/map.rs
+++ b/src/libstd/collections/hash/map.rs
@@ -1218,6 +1218,7 @@ impl<K, V, S> Default for HashMap<K, V, S>
     where K: Eq + Hash,
           S: BuildHasher + Default,
 {
+    /// Creates an empty `HashMap<K, V, S>`, with the `Default` value for the hasher.
     fn default() -> HashMap<K, V, S> {
         HashMap::with_hasher(Default::default())
     }
@@ -2026,6 +2027,7 @@ impl Hasher for DefaultHasher {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl Default for RandomState {
+    /// Constructs a new `RandomState`.
     #[inline]
     fn default() -> RandomState {
         RandomState::new()
diff --git a/src/libstd/collections/hash/set.rs b/src/libstd/collections/hash/set.rs
index ca5137e9573..ff56747fee6 100644
--- a/src/libstd/collections/hash/set.rs
+++ b/src/libstd/collections/hash/set.rs
@@ -665,6 +665,7 @@ impl<T, S> Default for HashSet<T, S>
     where T: Eq + Hash,
           S: BuildHasher + Default,
 {
+    /// Creates an empty `HashSet<T, S>` with the `Default` value for the hasher.
     fn default() -> HashSet<T, S> {
         HashSet::with_hasher(Default::default())
     }
diff --git a/src/libstd/ffi/c_str.rs b/src/libstd/ffi/c_str.rs
index 2d5e8c04194..1c449712e1f 100644
--- a/src/libstd/ffi/c_str.rs
+++ b/src/libstd/ffi/c_str.rs
@@ -361,6 +361,7 @@ impl<'a> Default for &'a CStr {
 
 #[stable(feature = "cstr_default", since = "1.10.0")]
 impl Default for CString {
+    /// Creates an empty `CString`.
     fn default() -> CString {
         let a: &CStr = Default::default();
         a.to_owned()
diff --git a/src/libstd/ffi/os_str.rs b/src/libstd/ffi/os_str.rs
index 36cf4ef758d..d93d3c73622 100644
--- a/src/libstd/ffi/os_str.rs
+++ b/src/libstd/ffi/os_str.rs
@@ -170,6 +170,7 @@ impl ops::Deref for OsString {
 
 #[stable(feature = "osstring_default", since = "1.9.0")]
 impl Default for OsString {
+    /// Constructs an empty `OsString`.
     #[inline]
     fn default() -> OsString {
         OsString::new()
@@ -342,6 +343,7 @@ impl OsStr {
 
 #[stable(feature = "osstring_default", since = "1.9.0")]
 impl<'a> Default for &'a OsStr {
+    /// Creates an empty `OsStr`.
     #[inline]
     fn default() -> &'a OsStr {
         OsStr::new("")
diff --git a/src/libstd/sync/condvar.rs b/src/libstd/sync/condvar.rs
index 4c946e613ea..3db8b05b954 100644
--- a/src/libstd/sync/condvar.rs
+++ b/src/libstd/sync/condvar.rs
@@ -241,6 +241,7 @@ impl Condvar {
 
 #[stable(feature = "condvar_default", since = "1.9.0")]
 impl Default for Condvar {
+    /// Creates a `Condvar` which is ready to be waited on and notified.
     fn default() -> Condvar {
         Condvar::new()
     }
diff --git a/src/libstd/sync/mutex.rs b/src/libstd/sync/mutex.rs
index c8ae88c2331..098a3e44258 100644
--- a/src/libstd/sync/mutex.rs
+++ b/src/libstd/sync/mutex.rs
@@ -287,6 +287,7 @@ impl<T: ?Sized> Drop for Mutex<T> {
 
 #[stable(feature = "mutex_default", since = "1.9.0")]
 impl<T: ?Sized + Default> Default for Mutex<T> {
+    /// Creates a `Mutex<T>`, with the `Default` value for T.
     fn default() -> Mutex<T> {
         Mutex::new(Default::default())
     }
diff --git a/src/libstd/sync/rwlock.rs b/src/libstd/sync/rwlock.rs
index 4801bcffd08..7f053c6704b 100644
--- a/src/libstd/sync/rwlock.rs
+++ b/src/libstd/sync/rwlock.rs
@@ -311,6 +311,7 @@ impl<T: ?Sized + fmt::Debug> fmt::Debug for RwLock<T> {
 
 #[stable(feature = "rw_lock_default", since = "1.9.0")]
 impl<T: Default> Default for RwLock<T> {
+    /// Creates a new `RwLock<T>`, with the `Default` value for T.
     fn default() -> RwLock<T> {
         RwLock::new(Default::default())
     }
diff --git a/src/libsyntax/ast.rs b/src/libsyntax/ast.rs
index 105f911dd57..40c8ba93bd5 100644
--- a/src/libsyntax/ast.rs
+++ b/src/libsyntax/ast.rs
@@ -362,6 +362,7 @@ impl Generics {
 }
 
 impl Default for Generics {
+    /// Creates an instance of `Generics`.
     fn default() ->  Generics {
         Generics {
             lifetimes: Vec::new(),
diff --git a/src/libsyntax/ptr.rs b/src/libsyntax/ptr.rs
index c3f8a977a65..58750158931 100644
--- a/src/libsyntax/ptr.rs
+++ b/src/libsyntax/ptr.rs
@@ -154,6 +154,7 @@ impl<T> P<[T]> {
 }
 
 impl<T> Default for P<[T]> {
+    /// Creates an empty `P<[T]>`.
     fn default() -> P<[T]> {
         P::new()
     }