std::ops docs: incorporated changes suggested in review

* fixed link typos and copy-paster errors
* rewrote Fn* explanations
* `RHS = Self` -> `RHS` is `Self` (added that to all applicable places as
  well)
* fixed up some links
* s/MutDeref/DerefMut
* removed remaining superfluous `fn main()`s
* fixed some minor phrasings and factual errors and inaccuracies

std::ops docs: Fix phrasing and factual errors/inaccuracies

6 files changed, 82 insertions, 58 deletions

diff --git a/src/libcore/ops/arith.rs b/src/libcore/ops/arith.rs
index 97fd8651b04..62007caedd3 100644
--- a/src/libcore/ops/arith.rs
+++ b/src/libcore/ops/arith.rs
@@ -10,8 +10,8 @@
 
 /// The addition operator `+`.
 ///
-/// Note that `RHS = Self` by default, but this is not mandatory. For example,
-/// [`std::time::SystemTime`] implements `Add<Duration>`, which permits
+/// Note that `RHS` is `Self` by default, but this is not mandatory. For
+/// example, [`std::time::SystemTime`] implements `Add<Duration>`, which permits
 /// operations of the form `SystemTime = SystemTime + Duration`.
 ///
 /// [`std::time::SystemTime`]: ../../std/time/struct.SystemTime.html
@@ -105,8 +105,8 @@ add_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f32 f64 }
 
 /// The subtraction operator `-`.
 ///
-/// Note that `RHS = Self` by default, but this is not mandatory. For example,
-/// [std::time::SystemTime] implements `Sub<Duration>`, which permits
+/// Note that `RHS` is `Self` by default, but this is not mandatory. For
+/// example, [`std::time::SystemTime`] implements `Sub<Duration>`, which permits
 /// operations of the form `SystemTime = SystemTime - Duration`.
 ///
 /// [`std::time::SystemTime`]: ../../std/time/struct.SystemTime.html
@@ -200,7 +200,7 @@ sub_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f32 f64 }
 
 /// The multiplication operator `*`.
 ///
-/// Note that `RHS = Self` by default, but this is not mandatory.
+/// Note that `RHS` is `Self` by default, but this is not mandatory.
 ///
 /// # Examples
 ///
@@ -317,7 +317,7 @@ mul_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f32 f64 }
 
 /// The division operator `/`.
 ///
-/// Note that `RHS = Self` by default, but this is not mandatory.
+/// Note that `RHS` is `Self` by default, but this is not mandatory.
 ///
 /// # Examples
 ///
@@ -455,6 +455,8 @@ div_impl_float! { f32 f64 }
 
 /// The remainder operator `%`.
 ///
+/// Note that `RHS` is `Self` by default, but this is not mandatory.
+///
 /// # Examples
 ///
 /// This example implements `Rem` on a `SplitSlice` object. After `Rem` is
diff --git a/src/libcore/ops/bit.rs b/src/libcore/ops/bit.rs
index e6fadf616b0..0bc5e554cb3 100644
--- a/src/libcore/ops/bit.rs
+++ b/src/libcore/ops/bit.rs
@@ -68,6 +68,8 @@ not_impl! { bool usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 }
 
 /// The bitwise AND operator `&`.
 ///
+/// Note that `RHS` is `Self` by default, but this is not mandatory.
+///
 /// # Examples
 ///
 /// An implementation of `BitAnd` for a wrapper around `bool`.
@@ -147,6 +149,8 @@ bitand_impl! { bool usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 }
 
 /// The bitwise OR operator `|`.
 ///
+/// Note that `RHS` is `Self` by default, but this is not mandatory.
+///
 /// # Examples
 ///
 /// An implementation of `BitOr` for a wrapper around `bool`.
@@ -226,6 +230,8 @@ bitor_impl! { bool usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 }
 
 /// The bitwise XOR operator `^`.
 ///
+/// Note that `RHS` is `Self` by default, but this is not mandatory.
+///
 /// # Examples
 ///
 /// An implementation of `BitXor` that lifts `^` to a wrapper around `bool`.
diff --git a/src/libcore/ops/deref.rs b/src/libcore/ops/deref.rs
index ac5ff1556f4..a2e7c44cb24 100644
--- a/src/libcore/ops/deref.rs
+++ b/src/libcore/ops/deref.rs
@@ -111,7 +111,7 @@ impl<'a, T: ?Sized> Deref for &'a mut T {
 ///
 /// # More on `Deref` coercion
 ///
-/// If `T` implements `MutDeref<Target = U>`, and `x` is a value of type `T`,
+/// If `T` implements `DerefMut<Target = U>`, and `x` is a value of type `T`,
 /// then:
 /// * In mutable contexts, `*x` on non-pointer types is equivalent to
 ///   `*Deref::deref(&x)`.
diff --git a/src/libcore/ops/function.rs b/src/libcore/ops/function.rs
index 5a61e9b68b8..2cc4e72817f 100644
--- a/src/libcore/ops/function.rs
+++ b/src/libcore/ops/function.rs
@@ -8,27 +8,39 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-/// A version of the call operator that takes an immutable receiver.
+/// The version of the call operator that takes an immutable receiver.
 ///
-/// Closures only taking immutable references to captured variables
-/// automatically implement this trait, which allows them to be invoked.
-/// For mutably referenced captures, see [`FnMut`], and for consuming the
-/// capture, see [`FnOnce`].
+/// Instances of `Fn` can be called repeatedly without mutating state.
 ///
-/// You can use the [`Fn`] traits when you want to accept a closure as a
-/// parameter. Since both [`FnMut`] and [`FnOnce`] are supertraits of `Fn`, any
-/// instance of `Fn` can be used where a [`FnMut`] or [`FnOnce`] is expected.
+/// *This trait (`Fn`) is not to be confused with [function pointers][]
+/// (`fn`).*
+///
+/// `Fn` is implemented automatically by closures which only take immutable
+/// references to captured variables or don't capture anything at all, as well
+/// as (safe) [function pointers][] (with some caveats, see their documentation
+/// for more details). Additionally, for any type `F` that implements `Fn`, `&F`
+/// implements `Fn`, too.
+///
+/// Since both [`FnMut`] and [`FnOnce`] are supertraits of `Fn`, any
+/// instance of `Fn` can be used as a parameter where a [`FnMut`] or [`FnOnce`]
+/// is expected.
+///
+/// Use `Fn` as a bound when you want to accept a parameter of function-like
+/// type and need to call it repeatedly and without mutating state (e.g. when
+/// calling it concurrently). If you do not need such strict requirements, use
+/// [`FnMut`] or [`FnOnce`] as bounds.
 ///
 /// See the [chapter on closures in *The Rust Programming Language*][book] for
-/// more information about closures in general.
+/// some more information on this topic.
 ///
 /// Also of note is the special syntax for `Fn` traits (e.g.
 /// `Fn(usize, bool) -> usize`). Those interested in the technical details of
-/// this can refer to [the relevant section in *The Rustonomicon*][nomicon].
+/// this can refer to [the relevant section in the *Rustonomicon*][nomicon].
 ///
 /// [book]: ../../book/second-edition/ch13-01-closures.html
 /// [`FnMut`]: trait.FnMut.html
 /// [`FnOnce`]: trait.FnOnce.html
+/// [function pointers]: ../../std/primitive.fn.html
 /// [nomicon]: ../../nomicon/hrtb.html
 ///
 /// # Examples
@@ -61,29 +73,36 @@ pub trait Fn<Args> : FnMut<Args> {
     extern "rust-call" fn call(&self, args: Args) -> Self::Output;
 }
 
-/// A version of the call operator that takes a mutable receiver.
+/// The version of the call operator that takes a mutable receiver.
+///
+/// Instances of `FnMut` can be called repeatedly and may mutate state.
 ///
-/// Closures that might mutably reference captured variables automatically
-/// implement this trait, which allows them to be invoked. For immutably
-/// referenced captures, see [`Fn`], and for consuming the captures, see
-/// [`FnOnce`].
+/// `FnMut` is implemented automatically by closures which take mutable
+/// references to captured variables, as well as all types that implement
+/// [`Fn`], e.g. (safe) [function pointers][] (since `FnMut` is a supertrait of
+/// [`Fn`]). Additionally, for any type `F` that implements `FnMut`, `&mut F`
+/// implements `FnMut`, too.
 ///
-/// You can use the [`Fn`] traits when you want to accept a closure as a
-/// parameter. Since [`FnOnce`] is a supertrait of `FnMut`, any instance of
-/// `FnMut` can be used where a [`FnOnce`] is expected, and since [`Fn`] is a
-/// subtrait of `FnMut`, any instance of [`Fn`] can be used where [`FnMut`] is
-/// expected.
+/// Since [`FnOnce`] is a supertrait of `FnMut`, any instance of `FnMut` can be
+/// used where a [`FnOnce`] is expected, and since [`Fn`] is a subtrait of
+/// `FnMut`, any instance of [`Fn`] can be used where `FnMut` is expected.
+///
+/// Use `FnMut` as a bound when you want to accept a parameter of function-like
+/// type and need to call it repeatedly, while allowing it to mutate state.
+/// If you don't want the parameter to mutate state, use [`Fn`] as a
+/// bound; if you don't need to call it repeatedly, use [`FnOnce`].
 ///
 /// See the [chapter on closures in *The Rust Programming Language*][book] for
-/// more information about closures in general.
+/// some more information on this topic.
 ///
 /// Also of note is the special syntax for `Fn` traits (e.g.
 /// `Fn(usize, bool) -> usize`). Those interested in the technical details of
-/// this can refer to [the relevant section in *The Rustonomicon*][nomicon].
+/// this can refer to [the relevant section in the *Rustonomicon*][nomicon].
 ///
 /// [book]: ../../book/second-edition/ch13-01-closures.html
-/// [`Fn`]: trait.Fnhtml
+/// [`Fn`]: trait.Fn.html
 /// [`FnOnce`]: trait.FnOnce.html
+/// [function pointers]: ../../std/primitive.fn.html
 /// [nomicon]: ../../nomicon/hrtb.html
 ///
 /// # Examples
@@ -127,27 +146,35 @@ pub trait FnMut<Args> : FnOnce<Args> {
     extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output;
 }
 
-/// A version of the call operator that takes a by-value receiver.
+/// The version of the call operator that takes a by-value receiver.
+///
+/// Instances of `FnOnce` can be called, but might not be callable multiple
+/// times. Because of this, if the only thing known about a type is that it
+/// implements `FnOnce`, it can only be called once.
+///
+/// `FnOnce` is implemented automatically by closure that might consume captured
+/// variables, as well as all types that implement [`FnMut`], e.g. (safe)
+/// [function pointers][] (since `FnOnce` is a supertrait of [`FnMut`]).
 ///
-/// Closures that might take ownership of captured variables automatically
-/// implement this trait, which allows them to be invoked. For immutably
-/// referenced captures, see [`Fn`], and for mutably referenced captures,
-/// see [`FnMut`].
+/// Since both [`Fn`] and [`FnMut`] are subtraits of `FnOnce`, any instance of
+/// [`Fn`] or [`FnMut`] can be used where a `FnOnce` is expected.
 ///
-/// You can use the [`Fn`] traits when you want to accept a closure as a
-/// parameter. Since both [`Fn`] and [`FnMut`] are subtraits of `FnOnce`, any
-/// instance of [`Fn`] or [`FnMut`] can be used where a `FnOnce` is expected.
+/// Use `FnOnce` as a bound when you want to accept a parameter of function-like
+/// type and only need to call it once. If you need to call the parameter
+/// repeatedly, use [`FnMut`] as a bound; if you also need it to not mutate
+/// state, use [`Fn`].
 ///
 /// See the [chapter on closures in *The Rust Programming Language*][book] for
-/// more information about closures in general.
+/// some more information on this topic.
 ///
 /// Also of note is the special syntax for `Fn` traits (e.g.
 /// `Fn(usize, bool) -> usize`). Those interested in the technical details of
-/// this can refer to [the relevant section in *The Rustonomicon*][nomicon].
+/// this can refer to [the relevant section in the *Rustonomicon*][nomicon].
 ///
 /// [book]: ../../book/second-edition/ch13-01-closures.html
 /// [`Fn`]: trait.Fn.html
 /// [`FnMut`]: trait.FnMut.html
+/// [function pointers]: ../../std/primitive.fn.html
 /// [nomicon]: ../../nomicon/hrtb.html
 ///
 /// # Examples
diff --git a/src/libcore/ops/index.rs b/src/libcore/ops/index.rs
index 0652421511a..d65c0aba504 100644
--- a/src/libcore/ops/index.rs
+++ b/src/libcore/ops/index.rs
@@ -77,11 +77,9 @@ pub trait Index<Idx: ?Sized> {
 /// `container[index]` is actually syntactic sugar for
 /// `*container.index_mut(index)`, but only when used as a mutable value. If
 /// an immutable value is requested, the [`Index`] trait is used instead. This
-/// allows nice things such as `v[index] = value` if the type of `value`
-/// implements [`Copy`].
+/// allows nice things such as `v[index] = value`.
 ///
 /// [`Index`]: ../../std/ops/trait.Index.html
-/// [`Copy`]: ../../std/marker/trait.Copy.html
 ///
 /// # Examples
 ///
diff --git a/src/libcore/ops/range.rs b/src/libcore/ops/range.rs
index 6a405cfdb98..463a50491a8 100644
--- a/src/libcore/ops/range.rs
+++ b/src/libcore/ops/range.rs
@@ -12,7 +12,7 @@ use fmt;
 
 /// An unbounded range (`..`).
 ///
-/// `RangeFull` is primarily used as a [slicing index], it's shorthand is `..`.
+/// `RangeFull` is primarily used as a [slicing index], its shorthand is `..`.
 /// It cannot serve as an [`Iterator`] because it doesn't have a starting point.
 ///
 /// # Examples
@@ -101,7 +101,6 @@ impl<Idx: PartialOrd<Idx>> Range<Idx> {
     /// ```
     /// #![feature(range_contains)]
     ///
-    /// # fn main() {
     /// assert!(!(3..5).contains(2));
     /// assert!( (3..5).contains(3));
     /// assert!( (3..5).contains(4));
@@ -109,7 +108,6 @@ impl<Idx: PartialOrd<Idx>> Range<Idx> {
     ///
     /// assert!(!(3..3).contains(3));
     /// assert!(!(3..2).contains(3));
-    /// # }
     /// ```
     pub fn contains(&self, item: Idx) -> bool {
         (self.start <= item) && (item < self.end)
@@ -163,11 +161,9 @@ impl<Idx: PartialOrd<Idx>> RangeFrom<Idx> {
     /// ```
     /// #![feature(range_contains)]
     ///
-    /// # fn main() {
     /// assert!(!(3..).contains(2));
     /// assert!( (3..).contains(3));
     /// assert!( (3..).contains(1_000_000_000));
-    /// # }
     /// ```
     pub fn contains(&self, item: Idx) -> bool {
         (self.start <= item)
@@ -191,6 +187,8 @@ impl<Idx: PartialOrd<Idx>> RangeFrom<Idx> {
 /// a `for` loop directly. This won't compile:
 ///
 /// ```compile_fail,E0277
+/// // error[E0277]: the trait bound `std::ops::RangeTo<{integer}>:
+/// // std::iter::Iterator` is not satisfied
 /// for i in ..5 {
 ///     // ...
 /// }
@@ -234,11 +232,9 @@ impl<Idx: PartialOrd<Idx>> RangeTo<Idx> {
     /// ```
     /// #![feature(range_contains)]
     ///
-    /// # fn main() {
     /// assert!( (..5).contains(-1_000_000_000));
     /// assert!( (..5).contains(4));
     /// assert!(!(..5).contains(5));
-    /// # }
     /// ```
     pub fn contains(&self, item: Idx) -> bool {
         (item < self.end)
@@ -255,14 +251,12 @@ impl<Idx: PartialOrd<Idx>> RangeTo<Idx> {
 /// ```
 /// #![feature(inclusive_range,inclusive_range_syntax)]
 ///
-/// # fn main() {
 /// assert_eq!((3...5), std::ops::RangeInclusive { start: 3, end: 5 });
 /// assert_eq!(3 + 4 + 5, (3...5).sum());
 ///
 /// let arr = [0, 1, 2, 3];
 /// assert_eq!(arr[ ...2], [0,1,2  ]);
 /// assert_eq!(arr[1...2], [  1,2  ]);  // RangeInclusive
-/// # }
 /// ```
 #[derive(Clone, PartialEq, Eq, Hash)]  // not Copy -- see #27186
 #[unstable(feature = "inclusive_range", reason = "recently added, follows RFC", issue = "28237")]
@@ -295,7 +289,6 @@ impl<Idx: PartialOrd<Idx>> RangeInclusive<Idx> {
     /// ```
     /// #![feature(range_contains,inclusive_range_syntax)]
     ///
-    /// # fn main() {
     /// assert!(!(3...5).contains(2));
     /// assert!( (3...5).contains(3));
     /// assert!( (3...5).contains(4));
@@ -304,7 +297,6 @@ impl<Idx: PartialOrd<Idx>> RangeInclusive<Idx> {
     ///
     /// assert!( (3...3).contains(3));
     /// assert!(!(3...2).contains(3));
-    /// # }
     /// ```
     pub fn contains(&self, item: Idx) -> bool {
         self.start <= item && item <= self.end
@@ -330,6 +322,9 @@ impl<Idx: PartialOrd<Idx>> RangeInclusive<Idx> {
 ///
 /// ```compile_fail,E0277
 /// #![feature(inclusive_range_syntax)]
+///
+/// // error[E0277]: the trait bound `std::ops::RangeToInclusive<{integer}>:
+/// // std::iter::Iterator` is not satisfied
 /// for i in ...5 {
 ///     // ...
 /// }
@@ -341,11 +336,9 @@ impl<Idx: PartialOrd<Idx>> RangeInclusive<Idx> {
 /// ```
 /// #![feature(inclusive_range_syntax)]
 ///
-/// # fn main() {
 /// let arr = [0, 1, 2, 3];
 /// assert_eq!(arr[ ...2], [0,1,2  ]);  // RangeToInclusive
 /// assert_eq!(arr[1...2], [  1,2  ]);
-/// # }
 /// ```
 ///
 /// [`IntoIterator`]: ../iter/trait.Iterator.html
@@ -377,11 +370,9 @@ impl<Idx: PartialOrd<Idx>> RangeToInclusive<Idx> {
     /// ```
     /// #![feature(range_contains,inclusive_range_syntax)]
     ///
-    /// # fn main() {
     /// assert!( (...5).contains(-1_000_000_000));
     /// assert!( (...5).contains(5));
     /// assert!(!(...5).contains(6));
-    /// # }
     /// ```
     pub fn contains(&self, item: Idx) -> bool {
         (item <= self.end)