src/doc/rustdoc/src/documentation-tests.md

   1 # Documentation tests
   2
   3 `rustdoc` supports executing your documentation examples as tests. This makes sure
   4 that your tests are up to date and working.
   5
   6 The basic idea is this:
   7
   8 ```ignore
   9 /// # Examples
  10 ///
  11 /// ```
  12 /// let x = 5;
  13 /// ```
  14 ```
  15
  16 The triple backticks start and end code blocks. If this were in a file named `foo.rs`,
  17 running `rustdoc --test foo.rs` will extract this example, and then run it as a test.
  18
  19 Please note that by default, if no language is set for the block code, `rustdoc`
  20 assumes it is `Rust` code. So the following:
  21
  22 ```rust
  23 let x = 5;
  24 ```
  25
  26 is strictly equivalent to:
  27
  28 ```
  29 let x = 5;
  30 ```
  31
  32 There's some subtlety though! Read on for more details.
  33
  34 ## Pre-processing examples
  35
  36 In the example above, you'll note something strange: there's no `main`
  37 function! Forcing you to write `main` for every example, no matter how small,
  38 adds friction. So `rustdoc` processes your examples slightly before
  39 running them. Here's the full algorithm rustdoc uses to preprocess examples:
  40
  41 1. Any leading `#![foo]` attributes are left intact as crate attributes.
  42 2. Some common `allow` attributes are inserted, including
  43    `unused_variables`, `unused_assignments`, `unused_mut`,
  44    `unused_attributes`, and `dead_code`. Small examples often trigger
  45    these lints.
  46 3. If the example does not contain `extern crate`, then `extern crate
  47    <mycrate>;` is inserted (note the lack of `#[macro_use]`).
  48 4. Finally, if the example does not contain `fn main`, the remainder of the
  49    text is wrapped in `fn main() { your_code }`.
  50
  51 For more about that caveat in rule 3, see "Documeting Macros" below.
  52
  53 ## Hiding portions of the example
  54
  55 Sometimes, you need some setup code, or other things that would distract
  56 from your example, but are important to make the tests work. Consider
  57 an example block that looks like this:
  58
  59 ```text
  60 /// Some documentation.
  61 # fn foo() {}
  62 ```
  63
  64 It will render like this:
  65
  66 ```rust
  67 /// Some documentation.
  68 # fn foo() {}
  69 ```
  70
  71 Yes, that's right: you can add lines that start with `# `, and they will
  72 be hidden from the output, but will be used when compiling your code. You
  73 can use this to your advantage. In this case, documentation comments need
  74 to apply to some kind of function, so if I want to show you just a
  75 documentation comment, I need to add a little function definition below
  76 it. At the same time, it's only there to satisfy the compiler, so hiding
  77 it makes the example more clear. You can use this technique to explain
  78 longer examples in detail, while still preserving the testability of your
  79 documentation.
  80
  81 For example, imagine that we wanted to document this code:
  82
  83 ```rust
  84 let x = 5;
  85 let y = 6;
  86 println!("{}", x + y);
  87 ```
  88
  89 We might want the documentation to end up looking like this:
  90
  91 > First, we set `x` to five:
  92 >
  93 > ```rust
  94 > let x = 5;
  95 > # let y = 6;
  96 > # println!("{}", x + y);
  97 > ```
  98 >
  99 > Next, we set `y` to six:
 100 >
 101 > ```rust
 102 > # let x = 5;
 103 > let y = 6;
 104 > # println!("{}", x + y);
 105 > ```
 106 >
 107 > Finally, we print the sum of `x` and `y`:
 108 >
 109 > ```rust
 110 > # let x = 5;
 111 > # let y = 6;
 112 > println!("{}", x + y);
 113 > ```
 114
 115 To keep each code block testable, we want the whole program in each block, but
 116 we don't want the reader to see every line every time.  Here's what we put in
 117 our source code:
 118
 119 ```text
 120     First, we set `x` to five:
 121
 122     ```
 123     let x = 5;
 124     # let y = 6;
 125     # println!("{}", x + y);
 126     ```
 127
 128     Next, we set `y` to six:
 129
 130     ```
 131     # let x = 5;
 132     let y = 6;
 133     # println!("{}", x + y);
 134     ```
 135
 136     Finally, we print the sum of `x` and `y`:
 137
 138     ```
 139     # let x = 5;
 140     # let y = 6;
 141     println!("{}", x + y);
 142     ```
 143 ```
 144
 145 By repeating all parts of the example, you can ensure that your example still
 146 compiles, while only showing the parts that are relevant to that part of your
 147 explanation.
 148
 149 Another case where the use of `#` is handy is when you want to ignore
 150 error handling. Lets say you want the following,
 151
 152 ```ignore
 153 /// use std::io;
 154 /// let mut input = String::new();
 155 /// io::stdin().read_line(&mut input)?;
 156 ```
 157
 158 The problem is that `?` returns a `Result<T, E>` and test functions
 159 don't return anything so this will give a mismatched types error.
 160
 161 ```ignore
 162 /// A doc test using ?
 163 ///
 164 /// ```
 165 /// use std::io;
 166 /// # fn foo() -> io::Result<()> {
 167 /// let mut input = String::new();
 168 /// io::stdin().read_line(&mut input)?;
 169 /// # Ok(())
 170 /// # }
 171 /// ```
 172 # fn foo() {}
 173 ```
 174
 175 You can get around this by wrapping the code in a function. This catches
 176 and swallows the `Result<T, E>` when running tests on the docs. This
 177 pattern appears regularly in the standard library.
 178
 179 ### Documenting macros
 180
 181 Here’s an example of documenting a macro:
 182
 183 ```rust
 184 /// Panic with a given message unless an expression evaluates to true.
 185 ///
 186 /// # Examples
 187 ///
 188 /// ```
 189 /// # #[macro_use] extern crate foo;
 190 /// # fn main() {
 191 /// panic_unless!(1 + 1 == 2, “Math is broken.”);
 192 /// # }
 193 /// ```
 194 ///
 195 /// ```should_panic
 196 /// # #[macro_use] extern crate foo;
 197 /// # fn main() {
 198 /// panic_unless!(true == false, “I’m broken.”);
 199 /// # }
 200 /// ```
 201 #[macro_export]
 202 macro_rules! panic_unless {
 203     ($condition:expr, $($rest:expr),+) => ({ if ! $condition { panic!($($rest),+); } });
 204 }
 205 # fn main() {}
 206 ```
 207
 208 You’ll note three things: we need to add our own `extern crate` line, so that
 209 we can add the `#[macro_use]` attribute. Second, we’ll need to add our own
 210 `main()` as well (for reasons discussed above). Finally, a judicious use of
 211 `#` to comment out those two things, so they don’t show up in the output.
 212
 213 ## Attributes
 214
 215 There are a few annotations that are useful to help `rustdoc` do the right
 216 thing when testing your code:
 217
 218 ```rust
 219 /// ```ignore
 220 /// fn foo() {
 221 /// ```
 222 # fn foo() {}
 223 ```
 224
 225 The `ignore` directive tells Rust to ignore your code. This is almost never
 226 what you want, as it's the most generic. Instead, consider annotating it
 227 with `text` if it's not code, or using `#`s to get a working example that
 228 only shows the part you care about.
 229
 230 ```rust
 231 /// ```should_panic
 232 /// assert!(false);
 233 /// ```
 234 # fn foo() {}
 235 ```
 236
 237 `should_panic` tells `rustdoc` that the code should compile correctly, but
 238 not actually pass as a test.
 239
 240 ```text
 241 /// ```no_run
 242 /// loop {
 243 ///     println!("Hello, world");
 244 /// }
 245 /// ```
 246 # fn foo() {}
 247 ```
 248
 249 `compile_fail` tells `rustdoc` that the compilation should fail. If it
 250 compiles, then the test will fail. However please note that code failing
 251 with the current Rust release may work in a future release, as new features
 252 are added.
 253
 254 ```text
 255 /// ```compile_fail
 256 /// let x = 5;
 257 /// x += 2; // shouldn't compile!
 258 /// ```
 259 ```
 260
 261 The `no_run` attribute will compile your code, but not run it. This is
 262 important for examples such as "Here's how to retrieve a web page,"
 263 which you would want to ensure compiles, but might be run in a test
 264 environment that has no network access.