Rollup of 5 pull requests

src/doc/book/traits.md

@@ -275,7 +275,7 @@ won’t have its methods:
 [write]: ../std/io/trait.Write.html
 
 ```rust,ignore
-let mut f = std::fs::File::open("foo.txt").expect("Couldn’t open foo.txt");
+let mut f = std::fs::File::create("foo.txt").expect("Couldn’t create foo.txt");
 let buf = b"whatever"; // byte string literal. buf: &[u8; 8]
 let result = f.write(buf);
 # result.unwrap(); // ignore the error
@@ -294,7 +294,7 @@ We need to `use` the `Write` trait first:
 ```rust,ignore
 use std::io::Write;
 
-let mut f = std::fs::File::open("foo.txt").expect("Couldn’t open foo.txt");
+let mut f = std::fs::File::create("foo.txt").expect("Couldn’t create foo.txt");
 let buf = b"whatever";
 let result = f.write(buf);
 # result.unwrap(); // ignore the error

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/clone.rs

@@ -14,10 +14,14 @@
 //! assign them or pass them as arguments, the receiver will get a copy,
 //! leaving the original value in place. These types do not require
 //! allocation to copy and do not have finalizers (i.e. they do not
-//! contain owned boxes or implement `Drop`), so the compiler considers
+//! contain owned boxes or implement [`Drop`]), so the compiler considers
 //! them cheap and safe to copy. For other types copies must be made
-//! explicitly, by convention implementing the `Clone` trait and calling
-//! the `clone` method.
+//! explicitly, by convention implementing the [`Clone`] trait and calling
+//! the [`clone`][clone] method.
+//!
+//! [`Clone`]: trait.Clone.html
+//! [clone]: trait.Clone.html#tymethod.clone
+//! [`Drop`]: ../../std/ops/trait.Drop.html
 //!
 //! Basic usage example:
 //!
@@ -46,22 +50,22 @@
 
 /// A common trait for the ability to explicitly duplicate an object.
 ///
-/// Differs from `Copy` in that `Copy` is implicit and extremely inexpensive, while
+/// Differs from [`Copy`] in that [`Copy`] is implicit and extremely inexpensive, while
 /// `Clone` is always explicit and may or may not be expensive. In order to enforce
-/// these characteristics, Rust does not allow you to reimplement `Copy`, but you
+/// these characteristics, Rust does not allow you to reimplement [`Copy`], but you
 /// may reimplement `Clone` and run arbitrary code.
 ///
-/// Since `Clone` is more general than `Copy`, you can automatically make anything
-/// `Copy` be `Clone` as well.
+/// Since `Clone` is more general than [`Copy`], you can automatically make anything
+/// [`Copy`] be `Clone` as well.
 ///
 /// ## Derivable
 ///
 /// This trait can be used with `#[derive]` if all fields are `Clone`. The `derive`d
-/// implementation of `clone()` calls `clone()` on each field.
+/// implementation of [`clone()`] calls [`clone()`] on each field.
 ///
 /// ## How can I implement `Clone`?
 ///
-/// Types that are `Copy` should have a trivial implementation of `Clone`. More formally:
+/// Types that are [`Copy`] should have a trivial implementation of `Clone`. More formally:
 /// if `T: Copy`, `x: T`, and `y: &T`, then `let x = y.clone();` is equivalent to `let x = *y;`.
 /// Manual implementations should be careful to uphold this invariant; however, unsafe code
 /// must not rely on it to ensure memory safety.
@@ -70,6 +74,9 @@
 /// library only implements `Clone` up until arrays of size 32. In this case, the implementation of
 /// `Clone` cannot be `derive`d, but can be implemented as:
 ///
+/// [`Copy`]: ../../std/marker/trait.Copy.html
+/// [`clone()`]: trait.Clone.html#tymethod.clone
+///
 /// ```
 /// #[derive(Copy)]
 /// struct Stats {

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/marker.rs

@@ -126,7 +126,7 @@ pub trait Unsize<T: ?Sized> {
 /// }
 /// ```
 ///
-/// The `PointList` `struct` cannot implement `Copy`, because `Vec<T>` is not `Copy`. If we
+/// The `PointList` `struct` cannot implement `Copy`, because [`Vec<T>`] is not `Copy`. If we
 /// attempt to derive a `Copy` implementation, we'll get an error:
 ///
 /// ```text
@@ -136,10 +136,10 @@ pub trait Unsize<T: ?Sized> {
 /// ## When can my type _not_ be `Copy`?
 ///
 /// Some types can't be copied safely. For example, copying `&mut T` would create an aliased
-/// mutable reference, and copying `String` would result in two attempts to free the same buffer.
+/// mutable reference, and copying [`String`] would result in two attempts to free the same buffer.
 ///
-/// Generalizing the latter case, any type implementing `Drop` can't be `Copy`, because it's
-/// managing some resource besides its own `size_of::<T>()` bytes.
+/// Generalizing the latter case, any type implementing [`Drop`] can't be `Copy`, because it's
+/// managing some resource besides its own [`size_of::<T>()`] bytes.
 ///
 /// ## What if I derive `Copy` on a type that can't?
 ///
@@ -156,8 +156,7 @@ pub trait Unsize<T: ?Sized> {
 ///
 /// ## Derivable
 ///
-/// This trait can be used with `#[derive]` if all of its components implement `Copy` and the type
-/// implements `Clone`. The implementation will copy the bytes of each field using `memcpy`.
+/// This trait can be used with `#[derive]` if all of its components implement `Copy` and the type.
 ///
 /// ## How can I implement `Copy`?
 ///
@@ -178,6 +177,11 @@ pub trait Unsize<T: ?Sized> {
 ///
 /// There is a small difference between the two: the `derive` strategy will also place a `Copy`
 /// bound on type parameters, which isn't always desired.
+///
+/// [`Vec<T>`]: ../../std/vec/struct.Vec.html
+/// [`String`]: ../../std/string/struct.String.html
+/// [`Drop`]: ../../std/ops/trait.Drop.html
+/// [`size_of::<T>()`]: ../../std/mem/fn.size_of.html
 #[stable(feature = "rust1", since = "1.0.0")]
 #[lang = "copy"]
 pub trait Copy : Clone {
@@ -190,11 +194,11 @@ pub trait Copy : Clone {
 /// thread-safe. In other words, there is no possibility of data races
 /// when passing `&T` references between threads.
 ///
-/// As one would expect, primitive types like `u8` and `f64` are all
+/// As one would expect, primitive types like [`u8`] and [`f64`] are all
 /// `Sync`, and so are simple aggregate types containing them (like
 /// tuples, structs and enums). More instances of basic `Sync` types
 /// include "immutable" types like `&T` and those with simple
-/// inherited mutability, such as `Box<T>`, `Vec<T>` and most other
+/// inherited mutability, such as [`Box<T>`], [`Vec<T>`] and most other
 /// collection types. (Generic parameters need to be `Sync` for their
 /// container to be `Sync`.)
 ///
@@ -206,27 +210,42 @@ pub trait Copy : Clone {
 /// race.
 ///
 /// Types that are not `Sync` are those that have "interior
-/// mutability" in a non-thread-safe way, such as `Cell` and `RefCell`
-/// in `std::cell`. These types allow for mutation of their contents
+/// mutability" in a non-thread-safe way, such as [`Cell`] and [`RefCell`]
+/// in [`std::cell`]. These types allow for mutation of their contents
 /// even when in an immutable, aliasable slot, e.g. the contents of
-/// `&Cell<T>` can be `.set`, and do not ensure data races are
+/// [`&Cell<T>`][`Cell`] can be [`.set`], and do not ensure data races are
 /// impossible, hence they cannot be `Sync`. A higher level example
 /// of a non-`Sync` type is the reference counted pointer
-/// `std::rc::Rc`, because any reference `&Rc<T>` can clone a new
+/// [`std::rc::Rc`][`Rc`], because any reference [`&Rc<T>`][`Rc`] can clone a new
 /// reference, which modifies the reference counts in a non-atomic
 /// way.
 ///
 /// For cases when one does need thread-safe interior mutability,
-/// types like the atomics in `std::sync` and `Mutex` & `RWLock` in
-/// the `sync` crate do ensure that any mutation cannot cause data
+/// types like the atomics in [`std::sync`][`sync`] and [`Mutex`] / [`RwLock`] in
+/// the [`sync`] crate do ensure that any mutation cannot cause data
 /// races.  Hence these types are `Sync`.
 ///
-/// Any types with interior mutability must also use the `std::cell::UnsafeCell`
+/// Any types with interior mutability must also use the [`std::cell::UnsafeCell`]
 /// wrapper around the value(s) which can be mutated when behind a `&`
 /// reference; not doing this is undefined behavior (for example,
-/// `transmute`-ing from `&T` to `&mut T` is invalid).
+/// [`transmute`]-ing from `&T` to `&mut T` is invalid).
 ///
 /// This trait is automatically derived when the compiler determines it's appropriate.
+///
+/// [`u8`]: ../../std/primitive.u8.html
+/// [`f64`]: ../../std/primitive.f64.html
+/// [`Vec<T>`]: ../../std/vec/struct.Vec.html
+/// [`Box<T>`]: ../../std/boxed/struct.Box.html
+/// [`Cell`]: ../../std/cell/struct.Cell.html
+/// [`RefCell`]: ../../std/cell/struct.RefCell.html
+/// [`std::cell`]: ../../std/cell/index.html
+/// [`.set`]: ../../std/cell/struct.Cell.html#method.set
+/// [`Rc`]: ../../std/rc/struct.Rc.html
+/// [`sync`]: ../../std/sync/index.html
+/// [`Mutex`]: ../../std/sync/struct.Mutex.html
+/// [`RwLock`]: ../../std/sync/struct.RwLock.html
+/// [`std::cell::UnsafeCell`]: ../../std/cell/struct.UnsafeCell.html
+/// [`transmute`]: ../../std/mem/fn.transmute.html
 #[stable(feature = "rust1", since = "1.0.0")]
 #[lang = "sync"]
 #[rustc_on_unimplemented = "`{Self}` cannot be shared between threads safely"]