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

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

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

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

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

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

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

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

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

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

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

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

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

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)

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

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 [] }
 }
 

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

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

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

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,

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)

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
     }

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

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

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

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

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

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

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

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

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