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 From d328d6472e6a61820c92ed7a910dbbff734fe235 Mon Sep 17 00:00:00 2001 From: Carol Nichols Date: Wed, 3 Jun 2015 13:15:50 -0400 Subject: Add prelude to get Write --- src/libstd/macros.rs | 1 + 1 file changed, 1 insertion(+) (limited to 'src/libstd') diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs index a7c18783025..1a3fda53366 100644 --- a/src/libstd/macros.rs +++ b/src/libstd/macros.rs @@ -126,6 +126,7 @@ macro_rules! println { /// ``` /// use std::io; /// use std::fs::File; +/// use std::io::prelude::*; /// /// fn write_to_file_using_try() -> Result<(), io::Error> { /// let mut file = try!(File::create("my_best_friends.txt")); -- cgit 1.4.1-3-g733a5 From a41fd590a8142b524d6a6d34e8977906d6787368 Mon Sep 17 00:00:00 2001 From: Carol Nichols Date: Wed, 3 Jun 2015 13:23:20 -0400 Subject: Use write_all instead of write_line --- src/libstd/macros.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs index 1a3fda53366..cbb28804459 100644 --- a/src/libstd/macros.rs +++ b/src/libstd/macros.rs @@ -130,14 +130,14 @@ macro_rules! println { /// /// 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.")); +/// try!(file.write_all(b"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.") { +/// match file.write_all(b"This is a list of my best friends.") { /// Ok(_) => (), /// Err(e) => return Err(e), /// } -- cgit 1.4.1-3-g733a5 From 80322e2e970bc7d2d36c14fb63f753fe39acf63e Mon Sep 17 00:00:00 2001 From: Carol Nichols Date: Wed, 3 Jun 2015 13:23:40 -0400 Subject: Return Ok(()) instead of Ok() --- src/libstd/macros.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs index cbb28804459..26ace45890c 100644 --- a/src/libstd/macros.rs +++ b/src/libstd/macros.rs @@ -132,7 +132,7 @@ macro_rules! println { /// let mut file = try!(File::create("my_best_friends.txt")); /// try!(file.write_all(b"This is a list of my best friends.")); /// println!("I wrote to the file"); -/// Ok() +/// Ok(()) /// } /// // This is equivalent to: /// fn write_to_file_using_match() -> Result<(), io::Error> { @@ -142,7 +142,7 @@ macro_rules! println { /// Err(e) => return Err(e), /// } /// println!("I wrote to the file"); -/// Ok() +/// Ok(()) /// } /// ``` #[macro_export] -- cgit 1.4.1-3-g733a5 From c692d75b5a595ef5939473aef20e1751d4e0e1f5 Mon Sep 17 00:00:00 2001 From: Carol Nichols Date: Wed, 3 Jun 2015 13:23:55 -0400 Subject: Indent 4 spaces instead of 2 --- src/libstd/macros.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs index 26ace45890c..706571b67c9 100644 --- a/src/libstd/macros.rs +++ b/src/libstd/macros.rs @@ -138,8 +138,8 @@ macro_rules! println { /// fn write_to_file_using_match() -> Result<(), io::Error> { /// let mut file = try!(File::create("my_best_friends.txt")); /// match file.write_all(b"This is a list of my best friends.") { -/// Ok(_) => (), -/// Err(e) => return Err(e), +/// Ok(_) => (), +/// Err(e) => return Err(e), /// } /// println!("I wrote to the file"); /// Ok(()) -- cgit 1.4.1-3-g733a5 From 24808fa076a2cf86c32e138d95c68e3ee4c7a0fc Mon Sep 17 00:00:00 2001 From: webmobster Date: Wed, 3 Jun 2015 13:47:07 +0100 Subject: Add priority policy to RWLock API Documentation --- src/libstd/sync/rwlock.rs | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/sync/rwlock.rs b/src/libstd/sync/rwlock.rs index e7c3d744c17..857d8889b7c 100644 --- a/src/libstd/sync/rwlock.rs +++ b/src/libstd/sync/rwlock.rs @@ -24,6 +24,10 @@ use sys_common::rwlock as sys; /// of the underlying data (exclusive access) and the read portion of this lock /// typically allows for read-only access (shared access). /// +/// The priority policy of the lock is dependent on the underlying operating +/// system's implementation, and this type does not guarantee that any +/// particular policy will be used. +/// /// The type parameter `T` represents the data that this lock protects. It is /// required that `T` satisfies `Send` to be shared across threads and `Sync` to /// allow concurrent access through readers. The RAII guards returned from the -- cgit 1.4.1-3-g733a5