From fdb28267387593974f4157dcc9558c8757805230 Mon Sep 17 00:00:00 2001 From: Eric Findlay Date: Wed, 28 Oct 2015 10:39:22 +0900 Subject: [PATCH 1/4] Added try! example to documentation.md --- src/doc/trpl/documentation.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/src/doc/trpl/documentation.md b/src/doc/trpl/documentation.md index e101d4bc0d4dc..e130109e35492 100644 --- a/src/doc/trpl/documentation.md +++ b/src/doc/trpl/documentation.md @@ -373,6 +373,36 @@ we can add the `#[macro_use]` attribute. Second, we’ll need to add our own `main()` as well. Finally, a judicious use of `#` to comment out those two things, so they don’t show up in the output. +Another case where the use of `#` is handy is when you want to ignore +error handling. Lets say you want the following, + +```rust +/// use std::io; +/// let mut input = String::new(); +/// try!(io::stdin().read_line(&mut input)); +``` + +The problem is that `try!` returns a `Result` and test functions +don't return anything so this will give a mismatched types error. + +```rust +/// A doc test using try! +/// +/// ``` +/// use std::io; +/// # fn f() -> io::Result<()> { +/// let mut input = String::new(); +/// try!(io::stdin().read_line(&mut input)); +/// # Ok(()) +/// # } +/// # f(); +/// ``` +``` + +You can get around this by wrapping the code in a function. This catches +and swallows the `Result` when running tests on the docs. This +pattern appears regularly in the standard library. + ### Running documentation tests To run the tests, either: From b2c3745229e8a0472f2a4ebede7496572e6b6d0e Mon Sep 17 00:00:00 2001 From: Eric Findlay Date: Thu, 29 Oct 2015 09:43:54 +0900 Subject: [PATCH 2/4] Added "ignore" to rustdoc example, r=steveklabnik Fixes #29234 --- src/doc/trpl/documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/trpl/documentation.md b/src/doc/trpl/documentation.md index e130109e35492..191a51dffdbfc 100644 --- a/src/doc/trpl/documentation.md +++ b/src/doc/trpl/documentation.md @@ -376,7 +376,7 @@ things, so they don’t show up in the output. Another case where the use of `#` is handy is when you want to ignore error handling. Lets say you want the following, -```rust +```rust,ignore /// use std::io; /// let mut input = String::new(); /// try!(io::stdin().read_line(&mut input)); From 46b30ccd895d6fc990474cb6f130b41d0a9b8dcf Mon Sep 17 00:00:00 2001 From: Eric Findlay Date: Sun, 8 Nov 2015 10:03:58 +0900 Subject: [PATCH 3/4] Added foo() to rustdoc example, r=steveklabnik Fixes #29234 --- src/doc/trpl/documentation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/doc/trpl/documentation.md b/src/doc/trpl/documentation.md index 191a51dffdbfc..b3f79f2f1df9c 100644 --- a/src/doc/trpl/documentation.md +++ b/src/doc/trpl/documentation.md @@ -385,17 +385,17 @@ error handling. Lets say you want the following, The problem is that `try!` returns a `Result` and test functions don't return anything so this will give a mismatched types error. -```rust +```rust,ignore /// A doc test using try! /// /// ``` /// use std::io; -/// # fn f() -> io::Result<()> { +/// # fn foo() -> io::Result<()> { /// let mut input = String::new(); /// try!(io::stdin().read_line(&mut input)); /// # Ok(()) /// # } -/// # f(); +/// # foo(); /// ``` ``` From dda7a3c2a195b7d99f4173f3636a8a7d25ca8c0c Mon Sep 17 00:00:00 2001 From: Eric Findlay Date: Sun, 8 Nov 2015 11:00:03 +0900 Subject: [PATCH 4/4] Fixed "foo()" in try! example, r=steveklabnik --- src/doc/trpl/documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/trpl/documentation.md b/src/doc/trpl/documentation.md index b3f79f2f1df9c..dc91c90b0fd62 100644 --- a/src/doc/trpl/documentation.md +++ b/src/doc/trpl/documentation.md @@ -395,8 +395,8 @@ don't return anything so this will give a mismatched types error. /// try!(io::stdin().read_line(&mut input)); /// # Ok(()) /// # } -/// # foo(); /// ``` +# fn foo() {} ``` You can get around this by wrapping the code in a function. This catches