Skip to content

Commit 5414c85

Browse files
author
lukaramu
committed
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
1 parent ffa327b commit 5414c85

File tree

1 file changed

+74
-21
lines changed

1 file changed

+74
-21
lines changed

src/libcore/ops/function.rs

Lines changed: 74 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -10,24 +10,37 @@
1010

1111
/// A version of the call operator that takes an immutable receiver.
1212
///
13-
/// # Examples
13+
/// Closures only taking immutable references to captured variables
14+
/// automatically implement this trait, which allows them to be invoked.
15+
/// For mutably referenced captures, see [`FnMut`], and for consuming the
16+
/// capture, see [`FnOnce`].
17+
///
18+
/// You can use the [`Fn`] traits when you want to accept a closure as a
19+
/// parameter. Since both [`FnMut`] and [`FnOnce`] are supertraits of `Fn`, any
20+
/// instance of `Fn` can be used where a [`FnMut`] or [`FnOnce`] is expected.
21+
///
22+
/// See the [chapter on closures in *The Rust Programming Language*][book] for
23+
/// more information about closures in general.
1424
///
15-
/// Closures automatically implement this trait, which allows them to be
16-
/// invoked. Note, however, that `Fn` takes an immutable reference to any
17-
/// captured variables. To take a mutable capture, implement [`FnMut`], and to
18-
/// consume the capture, implement [`FnOnce`].
25+
/// Also of note is the special syntax for `Fn` traits (e.g.
26+
/// `Fn(usize, bool) -> usize`). Those interested in the technical details of
27+
/// this can refer to [the relevant section in *The Rustonomicon*][nomicon].
1928
///
29+
/// [book]: ../../book/second-edition/ch13-01-closures.html
2030
/// [`FnMut`]: trait.FnMut.html
2131
/// [`FnOnce`]: trait.FnOnce.html
32+
/// [nomicon]: ../../nomicon/hrtb.html
33+
///
34+
/// # Examples
35+
///
36+
/// ## Calling a closure
2237
///
2338
/// ```
2439
/// let square = |x| x * x;
2540
/// assert_eq!(square(5), 25);
2641
/// ```
2742
///
28-
/// Closures can also be passed to higher-level functions through a `Fn`
29-
/// parameter (or a `FnMut` or `FnOnce` parameter, which are supertraits of
30-
/// `Fn`).
43+
/// ## Using a `Fn` parameter
3144
///
3245
/// ```
3346
/// fn call_with_one<F>(func: F) -> usize
@@ -43,17 +56,39 @@
4356
#[rustc_paren_sugar]
4457
#[fundamental] // so that regex can rely that `&str: !FnMut`
4558
pub trait Fn<Args> : FnMut<Args> {
46-
/// This is called when the call operator is used.
59+
/// Performs the call operation.
4760
#[unstable(feature = "fn_traits", issue = "29625")]
4861
extern "rust-call" fn call(&self, args: Args) -> Self::Output;
4962
}
5063

5164
/// A version of the call operator that takes a mutable receiver.
5265
///
66+
/// Closures that might mutably reference captured variables automatically
67+
/// implement this trait, which allows them to be invoked. For immutably
68+
/// referenced captures, see [`Fn`], and for consuming the captures, see
69+
/// [`FnOnce`].
70+
///
71+
/// You can use the [`Fn`] traits when you want to accept a closure as a
72+
/// parameter. Since [`FnOnce`] is a supertrait of `FnMut`, any instance of
73+
/// `FnMut` can be used where a [`FnOnce`] is expected, and since [`Fn`] is a
74+
/// subtrait of `FnMut`, any instance of [`Fn`] can be used where [`FnMut`] is
75+
/// expected.
76+
///
77+
/// See the [chapter on closures in *The Rust Programming Language*][book] for
78+
/// more information about closures in general.
79+
///
80+
/// Also of note is the special syntax for `Fn` traits (e.g.
81+
/// `Fn(usize, bool) -> usize`). Those interested in the technical details of
82+
/// this can refer to [the relevant section in *The Rustonomicon*][nomicon].
83+
///
84+
/// [book]: ../../book/second-edition/ch13-01-closures.html
85+
/// [`Fn`]: trait.Fnhtml
86+
/// [`FnOnce`]: trait.FnOnce.html
87+
/// [nomicon]: ../../nomicon/hrtb.html
88+
///
5389
/// # Examples
5490
///
55-
/// Closures that mutably capture variables automatically implement this trait,
56-
/// which allows them to be invoked.
91+
/// ## Calling a mutably capturing closure
5792
///
5893
/// ```
5994
/// let mut x = 5;
@@ -64,8 +99,7 @@ pub trait Fn<Args> : FnMut<Args> {
6499
/// assert_eq!(x, 25);
65100
/// ```
66101
///
67-
/// Closures can also be passed to higher-level functions through a `FnMut`
68-
/// parameter (or a `FnOnce` parameter, which is a supertrait of `FnMut`).
102+
/// ## Using a `FnMut` parameter
69103
///
70104
/// ```
71105
/// fn do_twice<F>(mut func: F)
@@ -88,39 +122,58 @@ pub trait Fn<Args> : FnMut<Args> {
88122
#[rustc_paren_sugar]
89123
#[fundamental] // so that regex can rely that `&str: !FnMut`
90124
pub trait FnMut<Args> : FnOnce<Args> {
91-
/// This is called when the call operator is used.
125+
/// Performs the call operation.
92126
#[unstable(feature = "fn_traits", issue = "29625")]
93127
extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output;
94128
}
95129

96130
/// A version of the call operator that takes a by-value receiver.
97131
///
132+
/// Closures that might take ownership of captured variables automatically
133+
/// implement this trait, which allows them to be invoked. For immutably
134+
/// referenced captures, see [`Fn`], and for mutably referenced captures,
135+
/// see [`FnMut`].
136+
///
137+
/// You can use the [`Fn`] traits when you want to accept a closure as a
138+
/// parameter. Since both [`Fn`] and [`FnMut`] are subtraits of `FnOnce`, any
139+
/// instance of [`Fn`] or [`FnMut`] can be used where a `FnOnce` is expected.
140+
///
141+
/// See the [chapter on closures in *The Rust Programming Language*][book] for
142+
/// more information about closures in general.
143+
///
144+
/// Also of note is the special syntax for `Fn` traits (e.g.
145+
/// `Fn(usize, bool) -> usize`). Those interested in the technical details of
146+
/// this can refer to [the relevant section in *The Rustonomicon*][nomicon].
147+
///
148+
/// [book]: ../../book/second-edition/ch13-01-closures.html
149+
/// [`Fn`]: trait.Fn.html
150+
/// [`FnMut`]: trait.FnMut.html
151+
/// [nomicon]: ../../nomicon/hrtb.html
152+
///
98153
/// # Examples
99154
///
100-
/// By-value closures automatically implement this trait, which allows them to
101-
/// be invoked.
155+
/// ## Calling a by-value closure
102156
///
103157
/// ```
104158
/// let x = 5;
105159
/// let square_x = move || x * x;
106160
/// assert_eq!(square_x(), 25);
107161
/// ```
108162
///
109-
/// By-value Closures can also be passed to higher-level functions through a
110-
/// `FnOnce` parameter.
163+
/// ## Using a `FnOnce` parameter
111164
///
112165
/// ```
113166
/// fn consume_with_relish<F>(func: F)
114167
/// where F: FnOnce() -> String
115168
/// {
116169
/// // `func` consumes its captured variables, so it cannot be run more
117-
/// // than once
170+
/// // than once.
118171
/// println!("Consumed: {}", func());
119172
///
120173
/// println!("Delicious!");
121174
///
122175
/// // Attempting to invoke `func()` again will throw a `use of moved
123-
/// // value` error for `func`
176+
/// // value` error for `func`.
124177
/// }
125178
///
126179
/// let x = String::from("x");
@@ -138,7 +191,7 @@ pub trait FnOnce<Args> {
138191
#[stable(feature = "fn_once_output", since = "1.12.0")]
139192
type Output;
140193

141-
/// This is called when the call operator is used.
194+
/// Performs the call operation.
142195
#[unstable(feature = "fn_traits", issue = "29625")]
143196
extern "rust-call" fn call_once(self, args: Args) -> Self::Output;
144197
}

0 commit comments

Comments
 (0)