From 9634bcbd3d120e7a13b62bb47e882fc9ce6338cd Mon Sep 17 00:00:00 2001 From: Carol Nichols Date: Wed, 3 Jun 2015 10:12:16 -0400 Subject: Improve `try!` docs to make clearer it returns `Result`. 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. --- src/libstd/macros.rs | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) (limited to 'src/libstd') diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs index 32193b4089d..a7c18783025 100644 --- a/src/libstd/macros.rs +++ b/src/libstd/macros.rs @@ -117,7 +117,33 @@ macro_rules! println { } /// Helper macro for unwrapping `Result` values while returning early with an -/// error if the value of the expression is `Err`. +/// error if the value of the expression is `Err`. Can only be used in +/// functions that return `Result` because of the early return of `Err` that +/// it provides. +/// +/// # Examples +/// +/// ``` +/// use std::io; +/// use std::fs::File; +/// +/// fn write_to_file_using_try() -> Result<(), io::Error> { +/// let mut file = try!(File::create("my_best_friends.txt")); +/// try!(file.write_line("This is a list of my best friends.")); +/// println!("I wrote to the file"); +/// Ok() +/// } +/// // This is equivalent to: +/// fn write_to_file_using_match() -> Result<(), io::Error> { +/// 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), +/// } +/// println!("I wrote to the file"); +/// Ok() +/// } +/// ``` #[macro_export] #[stable(feature = "rust1", since = "1.0.0")] macro_rules! try { -- cgit 1.4.1-3-g733a5