Revise Fn/FnMut/FnOnce documentation

Part of #29365.
* Moved explanations out of Examples section and expanded on them.
* Made the super-/subtrait relationships more explicit.
* Added links to the other traits, TRPL and the nomicon where appropriate
* Changed method summaries to be in 3rd person singular
* General copyediting

Author: lukaramu

src/libcore/ops/function.rs

@@ -10,24 +10,37 @@
 
 /// A version of the call operator that takes an immutable receiver.
 ///
-/// # Examples
+/// 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`].
+///
+/// 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.
+///
+/// See the [chapter on closures in *The Rust Programming Language*][book] for
+/// more information about closures in general.
 ///
-/// Closures automatically implement this trait, which allows them to be
-/// invoked. Note, however, that `Fn` takes an immutable reference to any
-/// captured variables. To take a mutable capture, implement [`FnMut`], and to
-/// consume the capture, implement [`FnOnce`].
+/// 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].
 ///
+/// [book]: ../../book/second-edition/ch13-01-closures.html
 /// [`FnMut`]: trait.FnMut.html
 /// [`FnOnce`]: trait.FnOnce.html
+/// [nomicon]: ../../nomicon/hrtb.html
+///
+/// # Examples
+///
+/// ## Calling a closure
 ///
 /// ```
 /// let square = |x| x * x;
 /// assert_eq!(square(5), 25);
 /// ```
 ///
-/// Closures can also be passed to higher-level functions through a `Fn`
-/// parameter (or a `FnMut` or `FnOnce` parameter, which are supertraits of
-/// `Fn`).
+/// ## Using a `Fn` parameter
 ///
 /// ```
 /// fn call_with_one<F>(func: F) -> usize
@@ -43,17 +56,39 @@
 #[rustc_paren_sugar]
 #[fundamental] // so that regex can rely that `&str: !FnMut`
 pub trait Fn<Args> : FnMut<Args> {
-    /// This is called when the call operator is used.
+    /// Performs the call operation.
     #[unstable(feature = "fn_traits", issue = "29625")]
     extern "rust-call" fn call(&self, args: Args) -> Self::Output;
 }
 
 /// A version of the call operator that takes a mutable receiver.
 ///
+/// 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`].
+///
+/// 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.
+///
+/// See the [chapter on closures in *The Rust Programming Language*][book] for
+/// more information about closures in general.
+///
+/// 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].
+///
+/// [book]: ../../book/second-edition/ch13-01-closures.html
+/// [`Fn`]: trait.Fnhtml
+/// [`FnOnce`]: trait.FnOnce.html
+/// [nomicon]: ../../nomicon/hrtb.html
+///
 /// # Examples
 ///
-/// Closures that mutably capture variables automatically implement this trait,
-/// which allows them to be invoked.
+/// ## Calling a mutably capturing closure
 ///
 /// ```
 /// let mut x = 5;
@@ -64,8 +99,7 @@ pub trait Fn<Args> : FnMut<Args> {
 /// assert_eq!(x, 25);
 /// ```
 ///
-/// Closures can also be passed to higher-level functions through a `FnMut`
-/// parameter (or a `FnOnce` parameter, which is a supertrait of `FnMut`).
+/// ## Using a `FnMut` parameter
 ///
 /// ```
 /// fn do_twice<F>(mut func: F)
@@ -88,39 +122,58 @@ pub trait Fn<Args> : FnMut<Args> {
 #[rustc_paren_sugar]
 #[fundamental] // so that regex can rely that `&str: !FnMut`
 pub trait FnMut<Args> : FnOnce<Args> {
-    /// This is called when the call operator is used.
+    /// Performs the call operation.
     #[unstable(feature = "fn_traits", issue = "29625")]
     extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output;
 }
 
 /// A version of the call operator that takes a by-value receiver.
 ///
+/// 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`].
+///
+/// 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.
+///
+/// See the [chapter on closures in *The Rust Programming Language*][book] for
+/// more information about closures in general.
+///
+/// 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].
+///
+/// [book]: ../../book/second-edition/ch13-01-closures.html
+/// [`Fn`]: trait.Fn.html
+/// [`FnMut`]: trait.FnMut.html
+/// [nomicon]: ../../nomicon/hrtb.html
+///
 /// # Examples
 ///
-/// By-value closures automatically implement this trait, which allows them to
-/// be invoked.
+/// ## Calling a by-value closure
 ///
 /// ```
 /// let x = 5;
 /// let square_x = move || x * x;
 /// assert_eq!(square_x(), 25);
 /// ```
 ///
-/// By-value Closures can also be passed to higher-level functions through a
-/// `FnOnce` parameter.
+/// ## Using a `FnOnce` parameter
 ///
 /// ```
 /// fn consume_with_relish<F>(func: F)
 ///     where F: FnOnce() -> String
 /// {
 ///     // `func` consumes its captured variables, so it cannot be run more
-///     // than once
+///     // than once.
 ///     println!("Consumed: {}", func());
 ///
 ///     println!("Delicious!");
 ///
 ///     // Attempting to invoke `func()` again will throw a `use of moved
-///     // value` error for `func`
+///     // value` error for `func`.
 /// }
 ///
 /// let x = String::from("x");
@@ -138,7 +191,7 @@ pub trait FnOnce<Args> {
     #[stable(feature = "fn_once_output", since = "1.12.0")]
     type Output;
 
-    /// This is called when the call operator is used.
+    /// Performs the call operation.
     #[unstable(feature = "fn_traits", issue = "29625")]
     extern "rust-call" fn call_once(self, args: Args) -> Self::Output;
 }