Rewrite and expand the closure section

[mdinger]

[EDIT] No longer WIP.

@huonw Your [closure blog post](http://huonw.github.io/blog/2015/05/finding-closure-in-rust/) was _amazingly_ helpful. I may not have gotten everything right but it helped me out a ton while working on this. I don't think certain parts of it were immediately obvious or accessible (for example, I had to read very carefully to realize `Fn` was only specifying how capturing works. I tried to put that front and center in this rewrite).

Of note: I think the the iterator docs in particular can be confusing especially with the complex bounding, associated type usage, shifting reference usage (seemingly at random), sometimes `&` and sometimes `&&` destructuring mixed with pointer dereferencing. On top of that, almost nothing is concrete is specified.

I think it'd be really hard for someone new to have any grasp of them. The analysis section was targeted at making that a little more comprehensible.

I'm not sure the other [function](http://rustbyexample.com/fn.html) sections fit with the new closure section (particularly [HOF](http://rustbyexample.com/fn/hof.html)) but I'm not sure how to change them and haven't tried too hard to fix them.

[rust-highfive]

r? @steveklabnik

(rust_highfive has picked a reviewer for you, use r? to override)

[steveklabnik]

supposedly?

[mdinger]

To someone unfamiliar with closures and particularly Rust's closures, they may not appear anonymous to the reader. All they have to go on is the fact that closures are also called anonymous functions. They don't have any evidence to support that fact themselves yet:

// Assign closure to `x`. It has a name `x` now. Anonymity implies no name but
// it has name `x` now.
let x = || 1; 

My intent was to point out the normal name and then to try to fill in the info so that the reader doesn't just have to trust that they're anonymous. He understands why it is.

[steveklabnik]

In a broad sense, 'anonymous functions' and 'closures' are two different things. Rust supports named and anonymous functions, and anonymous closures, but not named closures.

[steveklabnik]

(that said, i see what you're getting at here)

[mdinger]

Do you have examples to distinguish the 3? I interpreted the anonymity of a closure mainly in terms of the implicitly generated type it holds anonymously. That may or may not be correct but it's how I interpreted it.

[steveklabnik]

That may or may not be correct

Yeah, that's not what the anonymous part usually means.

Actually, come to think of it, Rust does not have anonymous functions currently, IIRC they're still closures with an empty environment.

JavaScript, for example, has anonymous closures:

counter = 0;
function () { return counter += 1; }

which you can assign to a var or just invoke immediately.

and named closures:

counter = 0;
function incr() { return counter +=1; }

you'd invoke this with incr(), because it has a name.

In Rust, you cannot give a name to a closure, ie, fn items are always functions, and don't close over their environment.

[mdinger]

Ah, I see what you mean by anonymous function though (which I wasn't sure about when you wrote that). I can tweak the wording then. Still, bringing the concepts of functions and closures together though makes Rust feel very cohesive.

[steveklabnik]

Oh yeah, for sure :)

[steveklabnik]

Looks great t ome!

[mdinger]

Excellent! I'll try to go over it again in a day or so again before submitting for final review.

[mdinger]

r? @steveklabnik I added a couple tweaks to wording and some more links. I didn't rebase but it passed make test so I'm waiting on travis to see if any issues pop up.

[steveklabnik]

Thanks! :)