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

1 files changed, 60 insertions, 33 deletions

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