[docs] Improve try! docs to make clearer it returns Result.
#25990
Conversation
The API documentation is not explicit enough that because `try!` returns `Err` early for you, you can only use it in functions that return `Result`. The book mentions this, but if you come across `try!` outside of the book and look it up in the docs, this restriction on the return type of the function is not particularly clear.
|
(rust_highfive has picked a reviewer for you, use r? to override) |
| /// let mut file = try!(File::create("my_best_friends.txt")); | ||
| /// match file.write_line("This is a list of my best friends.") { | ||
| /// Ok(_) => (), | ||
| /// Err(e) => return Err(e), |
There was a problem hiding this comment.
Could this be sure to use 4-space tabs instead of 2-space tabs?
Also, I think the write_line function has since been removed (old I/O?), but perhaps write_all with a byte-string literal could be used? I think this example may also need to import std::io::prelude::* to get the Write trait.
|
This note would have saved me a bunch of time. 👍 |
|
Thank you @alexcrichton, I made a bunch of tiny commits but I will squash them down into the first one when you've had a chance to take a look. I swear this now passes |
|
Very nice! I think I'd add another notion that this explicitly cannot be used in |
|
This looks good to me :) |
|
@bors rollup r+ |
|
📌 Commit c692d75 has been approved by |
|
@steveklabnik Can I suggest this for beta backport? |
|
@bluss docs are not really eligible for backports except in extreme
circumstances.
|
|
Ok. I thought docs would be a risk free backport, so it would be easy & beneficial to backport. Some other projects freeze code first and then allow extra time to only work on bugs & docs. |
|
We're being very, very conservative at first. |
The API documentation is not explicit enough that because `try!` returns `Err` early for you, you can only use it in functions that return `Result`. The book mentions this, but if you come across `try!` outside of the book and look it up in the docs, this restriction on the return type of the function is not particularly clear. I seriously had this epiphany a few days ago after working with Rust for MONTHS, and after seeing [a friend have to come to the same realization](http://joelmccracken.github.io/entries/a-simple-web-app-in-rust-pt-2a/), I'd like to save more people from this confusion :) 💖
The API documentation is not explicit enough that because
try!returnsErrearly for you, you can only use it in functions that returnResult. The book mentions this, but if you come acrosstry!outsideof the book and look it up in the docs, this restriction on the return
type of the function is not particularly clear.
I seriously had this epiphany a few days ago after working with Rust for MONTHS, and after seeing a friend have to come to the same realization, I'd like to save more people from this confusion :) 💖