Clarify documentation around test target setting.

There was some confusion about the wording in this section regarding
what happens with an example's `main` function. This tries to be more
explicit to clarify what happens when an example is marked as a test.

This also adds a few other clarifications and a link to the reference
documentation.

Closes #11528

src/doc/man/cargo-bench.md

@@ -86,11 +86,17 @@ following targets of the selected packages:
 
 The default behavior can be changed by setting the `bench` flag for the target
 in the manifest settings. Setting examples to `bench = true` will build and
-run the example as a benchmark. Setting targets to `bench = false` will stop
+run the example as a benchmark, replacing the example's `main` function with
-them from being benchmarked by default. Target selection options that take a
+the libtest harness.
-target by name ignore the `bench` flag and will always benchmark the given
+
+Setting targets to `bench = false` will stop them from being bencharmked by
+default. Target selection options that take a target by name (such as
+`--example foo`) ignore the `bench` flag and will always benchmark the given
 target.
 
+See [Configuring a target](../reference/cargo-targets.html#configuring-a-target)
+for more information on per-target settings.
+
 {{> options-targets-bin-auto-built }}
 
 {{> options-targets }}

src/doc/man/cargo-test.md

@@ -89,13 +89,20 @@ following targets of the selected packages:
 
 The default behavior can be changed by setting the `test` flag for the target
 in the manifest settings. Setting examples to `test = true` will build and run
-the example as a test. Setting targets to `test = false` will stop them from
+the example as a test, replacing the example's `main` function with the
-being tested by default. Target selection options that take a target by name
+libtest harness. If you don't want the `main` function replaced, also include
+`harness = false`, in which case the example will be built and executed as-is.
+
+Setting targets to `test = false` will stop them from being tested by default.
+Target selection options that take a target by name (such as `--example foo`)
 ignore the `test` flag and will always test the given target.
 
 Doc tests for libraries may be disabled by setting `doctest = false` for the
 library in the manifest.
 
+See [Configuring a target](../reference/cargo-targets.html#configuring-a-target)
+for more information on per-target settings.
+
 {{> options-targets-bin-auto-built }}
 
 {{> options-targets }}

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

@@ -120,10 +120,17 @@ OPTIONS
 
        The default behavior can be changed by setting the bench flag for the
        target in the manifest settings. Setting examples to bench = true will
-       build and run the example as a benchmark. Setting targets to bench =
+       build and run the example as a benchmark, replacing the example’s main
-       false will stop them from being benchmarked by default. Target selection
+       function with the libtest harness.
-       options that take a target by name ignore the bench flag and will always
+
-       benchmark the given target.
+       Setting targets to bench = false will stop them from being bencharmked
+       by default. Target selection options that take a target by name (such as
+       --example foo) ignore the bench flag and will always benchmark the given
+       target.
+
+       See Configuring a target
+       <https://doc.rust-lang.org/cargo/reference/cargo-targets.html#configuring-a-target>
+       for more information on per-target settings.
 
        Binary targets are automatically built if there is an integration test
        or benchmark being selected to benchmark. This allows an integration

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

@@ -128,14 +128,23 @@ OPTIONS
 
        The default behavior can be changed by setting the test flag for the
        target in the manifest settings. Setting examples to test = true will
-       build and run the example as a test. Setting targets to test = false
+       build and run the example as a test, replacing the example’s main
-       will stop them from being tested by default. Target selection options
+       function with the libtest harness. If you don’t want the main function
-       that take a target by name ignore the test flag and will always test the
+       replaced, also include harness = false, in which case the example will
-       given target.
+       be built and executed as-is.
+
+       Setting targets to test = false will stop them from being tested by
+       default. Target selection options that take a target by name (such as
+       --example foo) ignore the test flag and will always test the given
+       target.
 
        Doc tests for libraries may be disabled by setting doctest = false for
        the library in the manifest.
 
+       See Configuring a target
+       <https://doc.rust-lang.org/cargo/reference/cargo-targets.html#configuring-a-target>
+       for more information on per-target settings.
+
        Binary targets are automatically built if there is an integration test
        or benchmark being selected to test. This allows an integration test to
        execute the binary to exercise and test its behavior. The

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

@@ -143,11 +143,17 @@ following targets of the selected packages:
 
 The default behavior can be changed by setting the `bench` flag for the target
 in the manifest settings. Setting examples to `bench = true` will build and
-run the example as a benchmark. Setting targets to `bench = false` will stop
+run the example as a benchmark, replacing the example's `main` function with
-them from being benchmarked by default. Target selection options that take a
+the libtest harness.
-target by name ignore the `bench` flag and will always benchmark the given
+
+Setting targets to `bench = false` will stop them from being bencharmked by
+default. Target selection options that take a target by name (such as
+`--example foo`) ignore the `bench` flag and will always benchmark the given
 target.
 
+See [Configuring a target](../reference/cargo-targets.html#configuring-a-target)
+for more information on per-target settings.
+
 Binary targets are automatically built if there is an integration test or
 benchmark being selected to benchmark. This allows an integration
 test to execute the binary to exercise and test its behavior. 

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

@@ -146,13 +146,20 @@ following targets of the selected packages:
 
 The default behavior can be changed by setting the `test` flag for the target
 in the manifest settings. Setting examples to `test = true` will build and run
-the example as a test. Setting targets to `test = false` will stop them from
+the example as a test, replacing the example's `main` function with the
-being tested by default. Target selection options that take a target by name
+libtest harness. If you don't want the `main` function replaced, also include
+`harness = false`, in which case the example will be built and executed as-is.
+
+Setting targets to `test = false` will stop them from being tested by default.
+Target selection options that take a target by name (such as `--example foo`)
 ignore the `test` flag and will always test the given target.
 
 Doc tests for libraries may be disabled by setting `doctest = false` for the
 library in the manifest.
 
+See [Configuring a target](../reference/cargo-targets.html#configuring-a-target)
+for more information on per-target settings.
+
 Binary targets are automatically built if there is an integration test or
 benchmark being selected to test. This allows an integration
 test to execute the binary to exercise and test its behavior. 

src/etc/man/cargo-bench.1

@@ -145,11 +145,17 @@ available)
 .sp
 The default behavior can be changed by setting the \fBbench\fR flag for the target
 in the manifest settings. Setting examples to \fBbench = true\fR will build and
-run the example as a benchmark. Setting targets to \fBbench = false\fR will stop
+run the example as a benchmark, replacing the example\[cq]s \fBmain\fR function with
-them from being benchmarked by default. Target selection options that take a
+the libtest harness.
-target by name ignore the \fBbench\fR flag and will always benchmark the given
+.sp
+Setting targets to \fBbench = false\fR will stop them from being bencharmked by
+default. Target selection options that take a target by name (such as
+\fB\-\-example foo\fR) ignore the \fBbench\fR flag and will always benchmark the given
 target.
 .sp
+See \fIConfiguring a target\fR <https://doc.rust\-lang.org/cargo/reference/cargo\-targets.html#configuring\-a\-target>
+for more information on per\-target settings.
+.sp
 Binary targets are automatically built if there is an integration test or
 benchmark being selected to benchmark. This allows an integration
 test to execute the binary to exercise and test its behavior. 

src/etc/man/cargo-test.1

@@ -149,13 +149,20 @@ available)
 .sp
 The default behavior can be changed by setting the \fBtest\fR flag for the target
 in the manifest settings. Setting examples to \fBtest = true\fR will build and run
-the example as a test. Setting targets to \fBtest = false\fR will stop them from
+the example as a test, replacing the example\[cq]s \fBmain\fR function with the
-being tested by default. Target selection options that take a target by name
+libtest harness. If you don\[cq]t want the \fBmain\fR function replaced, also include
+\fBharness = false\fR, in which case the example will be built and executed as\-is.
+.sp
+Setting targets to \fBtest = false\fR will stop them from being tested by default.
+Target selection options that take a target by name (such as \fB\-\-example foo\fR)
 ignore the \fBtest\fR flag and will always test the given target.
 .sp
 Doc tests for libraries may be disabled by setting \fBdoctest = false\fR for the
 library in the manifest.
 .sp
+See \fIConfiguring a target\fR <https://doc.rust\-lang.org/cargo/reference/cargo\-targets.html#configuring\-a\-target>
+for more information on per\-target settings.
+.sp
 Binary targets are automatically built if there is an integration test or
 benchmark being selected to test. This allows an integration
 test to execute the binary to exercise and test its behavior.