Guide: Some Nitpicking

[mitsuhiko]

• The ok() documentation in the read_line example is not just inaccurate, it's misleading and wrong. .ok() does not abort the program, it returns an option. Maybe it needs to have an option section before to explain that type.
• the random number code uses % to make random numbers. This is a bad idea and generally guides are something people copy out of, so I would propose not bringing an antipattern into the mix.

[MatejLach]

• While I agree that it could've been worded better, Option<T> is explained in quite a bit of detail in this section and of course here.
  Perhaps it could be added that ok() returns an Option, altrough I feel that the Guide makes reasonable compromises in that it cannot cover everything at once.
  If one reads the whole thing, it becomes pretty clear what ok() does and if it's still unclear, one can look up the API docs (with examples for even better clarity).

Since the details of Option are explained right in the next chapter, I think it's fine as it is, but prehaps one could write something like:

"Rust provides a method on these IoResults called ok(), which does the same thing as our match statement, but assuming that we have a valid value. If we don't, it will return an Option, which we will explore in the next chapter, (for now, we can say that it will terminate our program)" or something like that.
I don't think any massive refactoring is needed, but I wonder what @steveklabnik thinks about this.

[huonw]

the random number code uses % to make random numbers. This is a bad idea and generally guides are something people copy out of, so I would propose not bringing an antipattern into the mix.

@steveklabnik People keep noticing and commenting on this, so I think we should at least have a more obvious note pointing people to gen_range as the correct solution, if not updating the code itself.

• Guide: guessing game #15729 (comment)
• rust-guide::13.3 Generating a secret number #15954
• guide: random secret number remarks #16354 (comment)

[steveklabnik]

The abort thing is just a straight-up error on my part, it should say that expect is what does the termination, you're right.

Is there a way we can have the range function without a trait? That's the blocking issue here.

[mitsuhiko]

+1 on a range function. The fact that the obvious way to do this is too hard for beginner docs indicates that an API adjustment might be a good idea.

[steveklabnik]

/cc @aturon , what do you think about removing the need for this trait?

[aturon]

@steveklabnik We could potentially do it by adding a default type parameter. Would that suffice? Or do you need to show the signature in full (in which case this would make it even more complex)?

[steveklabnik]

A default parameter would be fine. I don't actually need to show the type signature.

[steveklabnik]

@huonw is going to work on stabilizing rand, so hopefully we can just get something in here that doesn't require the trait import.

[steveklabnik]

I'm giving this a close, finally, as it's not even sure that rand is staying in the introduction at this point.