Bad example in `FnOnce` documentation

[alercah]

In the documentation for FnOnce, there are two examples. The first is

let x = 5;
let square_x = move || x * x;
assert_eq!(square_x(), 25);

This is not a FnOnce closure, as it never moves out of a variable in a way that would prevent it from calling again.

[durka]

As a technical point, all closures are FnOnce closures, because they may be called at least once. Fn implies FnMut which implies FnOnce. However, closures that modify their environment are only FnMut and FnOnce (not Fn) and closures that move out of their environment are only FnOnce.

[alercah]

Fair point. But as someone new to the documentation, I feel there's an implication in a few places (including the book, but unfortunately that section is frozen) that any move closure is only FnOnce and neither FnMut or Fn, which isn't true.

[durka]

Yes, it needs to be made more clear that those are totally orthogonal issues.

…

On Sun, Dec 31, 2017 at 1:43 PM, Alexis Hunt ***@***.***> wrote: Fair point. But as someone new to the documentation, I feel there's an implication in a few places (including the book, but unfortunately that section is frozen) that any move closure is only FnOnce and neither FnMut or Fn, which isn't true. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#47091 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAC3n7VvSR39J4QhiGG2dtcL6v6t_LBEks5tF9XEgaJpZM4RP1zb> .

[DevQps]

I personally think that the first example is better to be removed from the FnOnce page, since (in my opinion) it causes more confusion then that it actually helps. I guess that most people looking up FnOnce already know a bit about closures and might already know about the move || x * x; syntax. The page also references the book on closures, so I don't think its necessary to provide an example for calling by-value. The second example also includes the calling by value part.

I can imagine that users think the first example can only be called once (because they are on the FnOnce page), but this code also works:

fn main() {
    let x = 5;
    let square_x = move || x * x;
    println!("{}", square_x());
    println!("{}", square_x());
}

@steveklabnik What do you think about this? I can pick this up if you agree.

[steveklabnik]

Sounds good to me!