Rephrase wordings in testing docs

- Rephrase doctest exec model as "not guranteed and may change" instead
- Mention `#[bench]` in what cargo-bench automatically runs
- Make it clear for build/rustc when mentioning bin targets auto-built

Author: weihanglo

src/doc/man/cargo-bench.md

@@ -30,9 +30,9 @@ similarly named benchmarks like `foobar`):
 
 Benchmarks are built with the `--test` option to `rustc` which creates a
 special executable by linking your code with libtest. The executable
-automatically runs all functions annotated with the `#[test]` attribute.
-Cargo passes the `--bench` flag to the test harness to tell it to run only 
-benchmarks.
+automatically runs all functions annotated with `#[test]` and `#[bench]`
+attributes. Cargo passes the `--bench` flag to the test harness to tell
+it to run only benchmarks.
 
 The libtest harness may be disabled by setting `harness = false` in the target
 manifest settings, in which case your code will need to provide its own `main`

src/doc/man/cargo-test.md

@@ -47,11 +47,11 @@ extracts code samples from documentation comments of the library target, and
 then executes them.
 
 Different from normal test targets, each code block compiles to a doctest
-executable on the fly with `rustc`. These executables runs in parallel in
+executable on the fly with `rustc`. These executables run in parallel in
 separate processes. The compilation of a code block is in fact a part of test
 function controlled by libtest, so some options such as `--jobs` might not
-take effect. Note that this execution model of doctests is an undocumented
-implementation details, beware of depending on it.
+take effect. Note that this execution model of doctests is not guaranteed
+and may change in the future; beware of depending on it.
 
 See the [rustdoc book](https://doc.rust-lang.org/rustdoc/) for more information
 on writing doc tests.

src/doc/man/generated_txt/cargo-bench.txt

@@ -25,9 +25,9 @@ DESCRIPTION
 
        Benchmarks are built with the --test option to rustc which creates a
        special executable by linking your code with libtest. The executable
-       automatically runs all functions annotated with the #[test] attribute.
-       Cargo passes the --bench flag to the test harness to tell it to run only
-       benchmarks.
+       automatically runs all functions annotated with #[test] and #[bench]
+       attributes. Cargo passes the --bench flag to the test harness to tell it
+       to run only benchmarks.
 
        The libtest harness may be disabled by setting harness = false in the
        target manifest settings, in which case your code will need to provide
@@ -119,9 +119,9 @@ OPTIONS
        benchmark the given target.
 
        Binary targets are automatically built if there is an integration test
-       or benchmark. This allows an integration test to execute the binary to
-       exercise and test its behavior. The CARGO_BIN_EXE_<name> environment
-       variable
+       or benchmark being selected to benchmark. This allows an integration
+       test to execute the binary to exercise and test its behavior. The
+       CARGO_BIN_EXE_<name> environment variable
        <https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates>
        is set when the integration test is built so that it can use the env
        macro <https://doc.rust-lang.org/std/macro.env.html> to locate the

src/doc/man/generated_txt/cargo-build.txt

@@ -52,9 +52,9 @@ OPTIONS
        skipped if they have required-features that are missing.
 
        Binary targets are automatically built if there is an integration test
-       or benchmark. This allows an integration test to execute the binary to
-       exercise and test its behavior. The CARGO_BIN_EXE_<name> environment
-       variable
+       or benchmark being selected to build. This allows an integration test to
+       execute the binary to exercise and test its behavior. The
+       CARGO_BIN_EXE_<name> environment variable
        <https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates>
        is set when the integration test is built so that it can use the env
        macro <https://doc.rust-lang.org/std/macro.env.html> to locate the

src/doc/man/generated_txt/cargo-rustc.txt

@@ -43,9 +43,9 @@ OPTIONS
        binary and library targets of the selected package.
 
        Binary targets are automatically built if there is an integration test
-       or benchmark. This allows an integration test to execute the binary to
-       exercise and test its behavior. The CARGO_BIN_EXE_<name> environment
-       variable
+       or benchmark being selected to build. This allows an integration test to
+       execute the binary to exercise and test its behavior. The
+       CARGO_BIN_EXE_<name> environment variable
        <https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates>
        is set when the integration test is built so that it can use the env
        macro <https://doc.rust-lang.org/std/macro.env.html> to locate the

src/doc/man/generated_txt/cargo-test.txt

@@ -42,12 +42,12 @@ DESCRIPTION
        library target, and then executes them.
 
        Different from normal test targets, each code block compiles to a
-       doctest executable on the fly with rustc. These executables runs in
+       doctest executable on the fly with rustc. These executables run in
        parallel in separate processes. The compilation of a code block is in
        fact a part of test function controlled by libtest, so some options such
        as --jobs might not take effect. Note that this execution model of
-       doctests is an undocumented implementation details, beware of depending
-       on it.
+       doctests is not guaranteed and may change in the future; beware of
+       depending on it.
 
        See the rustdoc book <https://doc.rust-lang.org/rustdoc/> for more
        information on writing doc tests.
@@ -130,9 +130,9 @@ OPTIONS
        the library in the manifest.
 
        Binary targets are automatically built if there is an integration test
-       or benchmark. This allows an integration test to execute the binary to
-       exercise and test its behavior. The CARGO_BIN_EXE_<name> environment
-       variable
+       or benchmark being selected to test. This allows an integration test to
+       execute the binary to exercise and test its behavior. The
+       CARGO_BIN_EXE_<name> environment variable
        <https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates>
        is set when the integration test is built so that it can use the env
        macro <https://doc.rust-lang.org/std/macro.env.html> to locate the

src/doc/man/includes/options-targets-bin-auto-built.md

@@ -1,6 +1,7 @@
 Binary targets are automatically built if there is an integration test or
-benchmark. This allows an integration test to execute the binary to exercise
-and test its behavior. The `CARGO_BIN_EXE_<name>`
+benchmark being selected to {{lower actionverb}}. This allows an integration
+test to execute the binary to exercise and test its behavior. 
+The `CARGO_BIN_EXE_<name>`
 [environment variable](../reference/environment-variables.html#environment-variables-cargo-sets-for-crates)
 is set when the integration test is built so that it can use the
 [`env` macro](https://doc.rust-lang.org/std/macro.env.html) to locate the

src/doc/src/commands/cargo-bench.md

@@ -30,9 +30,9 @@ similarly named benchmarks like `foobar`):
 
 Benchmarks are built with the `--test` option to `rustc` which creates a
 special executable by linking your code with libtest. The executable
-automatically runs all functions annotated with the `#[test]` attribute.
-Cargo passes the `--bench` flag to the test harness to tell it to run only 
-benchmarks.
+automatically runs all functions annotated with `#[test]` and `#[bench]`
+attributes. Cargo passes the `--bench` flag to the test harness to tell
+it to run only benchmarks.
 
 The libtest harness may be disabled by setting `harness = false` in the target
 manifest settings, in which case your code will need to provide its own `main`
@@ -140,8 +140,9 @@ target by name ignore the `bench` flag and will always benchmark the given
 target.
 
 Binary targets are automatically built if there is an integration test or
-benchmark. This allows an integration test to execute the binary to exercise
-and test its behavior. The `CARGO_BIN_EXE_<name>`
+benchmark being selected to benchmark. This allows an integration
+test to execute the binary to exercise and test its behavior. 
+The `CARGO_BIN_EXE_<name>`
 [environment variable](../reference/environment-variables.html#environment-variables-cargo-sets-for-crates)
 is set when the integration test is built so that it can use the
 [`env` macro](https://doc.rust-lang.org/std/macro.env.html) to locate the

src/doc/src/commands/cargo-build.md

@@ -67,8 +67,9 @@ binary and library targets of the selected packages. Binaries are skipped if
 they have `required-features` that are missing.
 
 Binary targets are automatically built if there is an integration test or
-benchmark. This allows an integration test to execute the binary to exercise
-and test its behavior. The `CARGO_BIN_EXE_<name>`
+benchmark being selected to build. This allows an integration
+test to execute the binary to exercise and test its behavior. 
+The `CARGO_BIN_EXE_<name>`
 [environment variable](../reference/environment-variables.html#environment-variables-cargo-sets-for-crates)
 is set when the integration test is built so that it can use the
 [`env` macro](https://doc.rust-lang.org/std/macro.env.html) to locate the

src/doc/src/commands/cargo-rustc.md

@@ -54,8 +54,9 @@ When no target selection options are given, `cargo rustc` will build all
 binary and library targets of the selected package.
 
 Binary targets are automatically built if there is an integration test or
-benchmark. This allows an integration test to execute the binary to exercise
-and test its behavior. The `CARGO_BIN_EXE_<name>`
+benchmark being selected to build. This allows an integration
+test to execute the binary to exercise and test its behavior. 
+The `CARGO_BIN_EXE_<name>`
 [environment variable](../reference/environment-variables.html#environment-variables-cargo-sets-for-crates)
 is set when the integration test is built so that it can use the
 [`env` macro](https://doc.rust-lang.org/std/macro.env.html) to locate the