New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve documentation for each. #4305

Closed
wants to merge 1 commit into
base: master
from

Conversation

Projects
None yet
4 participants
@steveklabnik
Member

steveklabnik commented Dec 28, 2012

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

This comment has been minimized.

Member

steveklabnik commented Dec 28, 2012

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

View changes

src/libcore/vec.rs Outdated
* # Examples
* ~~~
* for [1,2,3].each |&i| {
* io::println(int::str(i));

This comment has been minimized.

@alan-andrade

alan-andrade Dec 28, 2012

Contributor

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

This comment has been minimized.

@steveklabnik

steveklabnik Dec 28, 2012

Member

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.

This comment has been minimized.

@alan-andrade

alan-andrade Dec 28, 2012

Contributor

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

Improve documentation for each.
Add description of arguments, and an example.
@steveklabnik

This comment has been minimized.

Member

steveklabnik commented Dec 28, 2012

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

@brendanzab

This comment has been minimized.

Member

brendanzab commented Dec 28, 2012

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

This comment has been minimized.

Contributor

alan-andrade commented Dec 28, 2012

Looks good to me 👍

@steveklabnik

This comment has been minimized.

Member

steveklabnik commented Dec 28, 2012

@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

This comment has been minimized.

Contributor

catamorphism commented Dec 28, 2012

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

This comment has been minimized.

Member

steveklabnik commented Dec 28, 2012

🤘

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment