Skip to content

Commit

Permalink
rustdoc book: talk about #![doc(test(...))] in doctests chapter
Browse files Browse the repository at this point in the history
  • Loading branch information
QuietMisdreavus committed Nov 4, 2017
1 parent 5fbadfc commit ce7a3a4
Showing 1 changed file with 8 additions and 6 deletions.
14 changes: 8 additions & 6 deletions src/doc/rustdoc/src/documentation-tests.md
Expand Up @@ -38,17 +38,19 @@ function! Forcing you to write `main` for every example, no matter how small,
adds friction. So `rustdoc` processes your examples slightly before
running them. Here's the full algorithm rustdoc uses to preprocess examples:

1. Any leading `#![foo]` attributes are left intact as crate attributes.
2. Some common `allow` attributes are inserted, including
1. Some common `allow` attributes are inserted, including
`unused_variables`, `unused_assignments`, `unused_mut`,
`unused_attributes`, and `dead_code`. Small examples often trigger
these lints.
3. If the example does not contain `extern crate`, then `extern crate
2. Any attributes specified with `#![doc(test(attr(...)))]` are added.
3. Any leading `#![foo]` attributes are left intact as crate attributes.
4. If the example does not contain `extern crate`, and
`#![doc(test(no_crate_inject))]` was not specified, then `extern crate
<mycrate>;` is inserted (note the lack of `#[macro_use]`).
4. Finally, if the example does not contain `fn main`, the remainder of the
5. Finally, if the example does not contain `fn main`, the remainder of the
text is wrapped in `fn main() { your_code }`.

For more about that caveat in rule 3, see "Documeting Macros" below.
For more about that caveat in rule 4, see "Documeting Macros" below.

## Hiding portions of the example

Expand Down Expand Up @@ -261,4 +263,4 @@ are added.
The `no_run` attribute will compile your code, but not run it. This is
important for examples such as "Here's how to retrieve a web page,"
which you would want to ensure compiles, but might be run in a test
environment that has no network access.
environment that has no network access.

0 comments on commit ce7a3a4

Please sign in to comment.