From ce7a3a458455600aec937354fa9b07cccce1e24e Mon Sep 17 00:00:00 2001 From: QuietMisdreavus Date: Sat, 4 Nov 2017 14:51:17 -0500 Subject: [PATCH] rustdoc book: talk about #![doc(test(...))] in doctests chapter --- src/doc/rustdoc/src/documentation-tests.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/src/doc/rustdoc/src/documentation-tests.md b/src/doc/rustdoc/src/documentation-tests.md index eb3e6a9dd5067..9c6b86d6ddc8e 100644 --- a/src/doc/rustdoc/src/documentation-tests.md +++ b/src/doc/rustdoc/src/documentation-tests.md @@ -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 ;` 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 @@ -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. \ No newline at end of file +environment that has no network access.