From 8e6b9b8e93a2acb3afc046c87774878ac2dd86d6 Mon Sep 17 00:00:00 2001 From: Alex Burka Date: Thu, 20 Aug 2015 18:41:24 -0400 Subject: [PATCH] emphasize that doctests don't run in bin crates --- src/doc/trpl/documentation.md | 12 ++++++------ src/doc/trpl/testing.md | 4 ++-- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/doc/trpl/documentation.md b/src/doc/trpl/documentation.md index 556af6625c0..7cbb9aefe5c 100644 --- a/src/doc/trpl/documentation.md +++ b/src/doc/trpl/documentation.md @@ -196,10 +196,10 @@ This will highlight according to whatever language you're showing off. If you're just showing plain text, choose `text`. It's important to choose the correct annotation here, because `rustdoc` uses it -in an interesting way: It can be used to actually test your examples, so that -they don't get out of date. If you have some C code but `rustdoc` thinks it's -Rust because you left off the annotation, `rustdoc` will complain when trying to -generate the documentation. +in an interesting way: It can be used to actually test your examples in a +library crate, so that they don't get out of date. If you have some C code but +`rustdoc` thinks it's Rust because you left off the annotation, `rustdoc` will +complain when trying to generate the documentation. ## Documentation as tests @@ -377,8 +377,8 @@ $ rustdoc --test path/to/my/crate/root.rs $ cargo test ``` -That's right, `cargo test` tests embedded documentation too. However, -`cargo test` will not test binary crates, only library ones. This is +That's right, `cargo test` tests embedded documentation too. **However, +`cargo test` will not test binary crates, only library ones.** This is due to the way `rustdoc` works: it links against the library to be tested, but with a binary, there’s nothing to link to. diff --git a/src/doc/trpl/testing.md b/src/doc/trpl/testing.md index a5a0127031a..cbf33febf87 100644 --- a/src/doc/trpl/testing.md +++ b/src/doc/trpl/testing.md @@ -355,8 +355,8 @@ Let's finally check out that third section: documentation tests. Nothing is better than documentation with examples. Nothing is worse than examples that don't actually work, because the code has changed since the documentation has been written. To this end, Rust supports automatically -running examples in your documentation. Here's a fleshed-out `src/lib.rs` -with examples: +running examples in your documentation (**note:** this only works in library +crates, not binary crates). Here's a fleshed-out `src/lib.rs` with examples: ```rust,ignore //! The `adder` crate provides functions that add numbers to other numbers.