Auto merge of #12032 - ehuss:clarify-test-option, r=weihanglo

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
-them from being benchmarked by default. Target selection options that take a
-target by name ignore the `bench` flag and will always benchmark the given
+run the example as a benchmark, replacing the example's `main` function with
+the libtest harness.
+
+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
-being tested by default. Target selection options that take a target by name
+the example as a test, replacing the example's `main` function with the
+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 =
-       false will stop them from being benchmarked by default. Target selection
-       options that take a target by name ignore the bench flag and will always
-       benchmark the given target.
+       build and run the example as a benchmark, replacing the example’s main
+       function with the libtest harness.
+
+       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
-       will stop them from being tested by default. Target selection options
-       that take a target by name ignore the test flag and will always test the
-       given target.
+       build and run the example as a test, replacing the example’s main
+       function with the 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
+       <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
-them from being benchmarked by default. Target selection options that take a
-target by name ignore the `bench` flag and will always benchmark the given
+run the example as a benchmark, replacing the example's `main` function with
+the libtest harness.
+
+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
-being tested by default. Target selection options that take a target by name
+the example as a test, replacing the example's `main` function with the
+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
-them from being benchmarked by default. Target selection options that take a
-target by name ignore the \fBbench\fR flag and will always benchmark the given
+run the example as a benchmark, replacing the example\[cq]s \fBmain\fR function with
+the libtest harness.
+.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
-being tested by default. Target selection options that take a target by name
+the example as a test, replacing the example\[cq]s \fBmain\fR function with the
+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.