doc: add more link references for tests guide

- Mention that in `src/` Cargo also collect doc tests.
- Remove outdated statement: Cargo no longer tests examples by default.
- Add a link to "Cargo Targets: Tests" to help people learn about it.

diff --git a/src/doc/src/guide/tests.md b/src/doc/src/guide/tests.md
index 50ee6ddb00042f10e428425ca648535c658ee9be..40cbe9f92e0b55a8c25e5e7977a92251acc6e67e 100644 (file)
--- a/src/doc/src/guide/tests.md
+++ b/src/doc/src/guide/tests.md
@@ -2,9 +2,9 @@
 
 Cargo can run your tests with the `cargo test` command. Cargo looks for tests
 to run in two places: in each of your `src` files and any tests in `tests/`.
-Tests in your `src` files should be unit tests, and tests in `tests/` should be
-integration-style tests. As such, you’ll need to import your crates into
-the files in `tests`.
+Tests in your `src` files should be unit tests and [documentation tests].
+Tests in `tests/` should be integration-style tests. As such, you’ll need to
+import your crates into the files in `tests`.
 
 Here's an example of running `cargo test` in our [package][def-package], which
 currently has no tests:
@@ -31,10 +31,14 @@ $ cargo test foo
 
 This will run any test with `foo` in its name.
 
-`cargo test` runs additional checks as well.  It will compile any
-examples you’ve included and will also test the examples in your
-documentation. Please see the [testing guide][testing] in the Rust
-documentation for more details.
+`cargo test` runs additional checks as well. It will compile any examples
+you’ve included to ensure they are still compiles. It also run documentation
+tests to ensure your code samples from documentation comments compiles.
+Please see the [testing guide][testing] in the Rust documentation for a general
+view of writing and organizing tests. See [Cargo Targets: Tests] to learn more
+about different styles of tests in Cargo.
 
+[documentation tests]: ../../rustdoc/write-documentation/documentation-tests.html
 [def-package]:  ../appendix/glossary.md#package  '"package" (glossary entry)'
 [testing]: ../../book/ch11-00-testing.html
+[Cargo Targets: Tests]: ../reference/cargo-targets.html#tests