From 63885f7f72974f71d08d21bf79676ef4dc1ccaf8 Mon Sep 17 00:00:00 2001 From: Tobias Stolzmann Date: Tue, 29 May 2018 21:43:10 +0200 Subject: [PATCH 1/2] =?UTF-8?q?Update=20rustdoc=20book=20to=20suggest=20us?= =?UTF-8?q?ing=20Termination=20trait=20instead=20of=20hidden=20=E2=80=98fo?= =?UTF-8?q?o=E2=80=99=20function?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/doc/rustdoc/src/documentation-tests.md | 40 ++++++++++++++++------ 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/src/doc/rustdoc/src/documentation-tests.md b/src/doc/rustdoc/src/documentation-tests.md index fd7d1713ca574..1fa385d652fd6 100644 --- a/src/doc/rustdoc/src/documentation-tests.md +++ b/src/doc/rustdoc/src/documentation-tests.md @@ -168,37 +168,55 @@ By repeating all parts of the example, you can ensure that your example still compiles, while only showing the parts that are relevant to that part of your explanation. -Another case where the use of `#` is handy is when you want to ignore -error handling. Lets say you want the following, + +## Using `?` in doc tests + +A complete error handling is often not useful in your example, as it would add +significant amounts of boilerplate code. Instead, you may want the following: ```ignore +/// ``` /// use std::io; /// let mut input = String::new(); /// io::stdin().read_line(&mut input)?; +/// ``` ``` -The problem is that `?` returns a `Result` and test functions -don't return anything so this will give a mismatched types error. +The problem is that `?` returns a `Result` and test functions don't +return anything, so this will give a mismatched types error. + +You can get around this limitation by manually adding a `main` that returns +`Result`, because `Result` implements the `Termination` trait: ```ignore /// A doc test using ? /// /// ``` /// use std::io; -/// # fn foo() -> io::Result<()> { +/// +/// fn main() -> io::Result<()> { +/// let mut input = String::new(); +/// io::stdin().read_line(&mut input)?; +/// Ok(()) +/// } +/// ``` +``` + +Together with the `# ` from the section above, you arrive at a solution that +appears to the reader as the initial idea but works with doc tests: + +```ignore +/// ``` +/// use std::io; +/// # fn main() -> io::Result<()> { /// let mut input = String::new(); /// io::stdin().read_line(&mut input)?; /// # Ok(()) /// # } /// ``` -# fn foo() {} ``` -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. - -### Documenting macros +## Documenting macros Here’s an example of documenting a macro: From 089da06cc437aa4764f958ff441e79d7fca6b148 Mon Sep 17 00:00:00 2001 From: Tobias Stolzmann Date: Thu, 31 May 2018 20:01:03 +0200 Subject: [PATCH 2/2] Improve wording --- src/doc/rustdoc/src/documentation-tests.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/doc/rustdoc/src/documentation-tests.md b/src/doc/rustdoc/src/documentation-tests.md index 1fa385d652fd6..2de69924b74dd 100644 --- a/src/doc/rustdoc/src/documentation-tests.md +++ b/src/doc/rustdoc/src/documentation-tests.md @@ -171,8 +171,9 @@ explanation. ## Using `?` in doc tests -A complete error handling is often not useful in your example, as it would add -significant amounts of boilerplate code. Instead, you may want the following: +When writing an example, it is rarely useful to include a complete error +handling, as it would add significant amounts of boilerplate code. Instead, you +may want the following: ```ignore /// ```