Improve documentation for each.

[steveklabnik]

Hey there!

I've just started using Rust, and I really like it. One of the things that makes Rust hard to use is its lack of documentation, which is obviously fine, given that Rust isn't production-ready yet.

I'd like to help change that.

To get started, I've just modified this one little description in the rustdoc. If this works out, and you all like my changes, I'll start working on more docs like this for the rest of core, and maybe the stdlib after that.

What do you think? Any and all feedback welcomed. ❤️

[steveklabnik]

I have updated to include an example of the breaking behavior, as well as made it use the Rust-standard 4 space indent: I'm too used to two spaces.

[alan-andrade]

So, this is returning true and continues iterating ? In line 1191 you have an explicit true and that confused me a bit.

[steveklabnik]

It returns () (unit).

The difference is actually between the for and the do. If you changed this one to do, you'd get

rustc fizzbuzz.rs
fizzbuzz.rs:2:27: 4:3 error: Do-block body must return bool, but returns () here. Perhaps you meant to write a `for`-loop?
fizzbuzz.rs:2 do [1,2,3,4,5].each |&i| {
fizzbuzz.rs:3 io::println(int::str(i));
fizzbuzz.rs:4 }
error: aborting due to previous error
make: *** [build] Error 101

Maybe making a bigger note of this is a good idea here.

[alan-andrade]

I think thats a good idea. This is implying that both 'for' and 'do' need to return a boolean.

[steveklabnik]

Updated to not use do/else by default, and include a note about their usage instead. This should make it more obvious.

[brendanzab]

Wouldn't it be better to emphasize the for/break syntax over the non-sugared version, seeing as it's the idiomatic way of using each? At any rate, I'd highly recommend adding a usage of break somewhere in there.

[alan-andrade]

Looks good to me 👍

[steveklabnik]

@bjz well, for me, API docs should cover just the API that they're covering, and refer to other documentation. Using two things together seems more like tutorial style docs than API docs.

I'll do whatever the Rust team wants in this regard. :)

[catamorphism]

Looks good to me as is. I know you know, but it should be retargeted against incoming, though :-)

Thanks for doing this and I'd welcome more like it! Documentation patches are wonderful!

[steveklabnik]

🤘

I've opened a new PR targeting incoming. I will give this a close.