doc: mention cargo test runs test targets serially

Author: weihanglo

src/doc/man/cargo-bench.md

@@ -28,10 +28,11 @@ similarly named benchmarks like `foobar`):
 
     cargo bench -- foo --exact
 
-Benchmarks are built with the `--test` option to `rustc` which creates an
-executable with a `main` function that automatically runs all functions
-annotated with the `#[bench]` attribute. Cargo passes the `--bench` flag to
-the test harness to tell it to run only benchmarks.
+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.
 
 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

@@ -12,7 +12,7 @@ cargo-test - Execute unit and integration tests of a package
 
 ## DESCRIPTION
 
-Compile and execute unit and integration tests.
+Compile and execute unit, integration, and documentation tests.
 
 The test filtering argument `TESTNAME` and all the arguments following the two
 dashes (`--`) are passed to the test binaries and thus to _libtest_ (rustc's
@@ -27,11 +27,14 @@ on 3 threads in parallel:
 
     cargo test foo -- --test-threads 3
 
-Tests are built with the `--test` option to `rustc` which creates an
-executable with a `main` function that automatically runs all functions
-annotated with the `#[test]` attribute in multiple threads. `#[bench]`
-annotated functions will also be run with one iteration to verify that they
-are functional.
+Tests 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 in multiple threads.
+`#[bench]` annotated functions will also be run with one iteration to verify
+that they are functional.
+
+If the package contains multiple test targets, each target compiles to a
+special executable as aforementioned, and then is run serially.
 
 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/generated_txt/cargo-bench.txt

@@ -23,10 +23,11 @@ DESCRIPTION
 
            cargo bench -- foo --exact
 
-       Benchmarks are built with the --test option to rustc which creates an
-       executable with a main function that automatically runs all functions
-       annotated with the #[bench] attribute. Cargo passes the --bench flag to
-       the test harness to tell it to run only benchmarks.
+       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.
 
        The libtest harness may be disabled by setting harness = false in the
        target manifest settings, in which case your code will need to provide

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

@@ -7,7 +7,7 @@ SYNOPSIS
        cargo test [options] [testname] [-- test-options]
 
 DESCRIPTION
-       Compile and execute unit and integration tests.
+       Compile and execute unit, integration, and documentation tests.
 
        The test filtering argument TESTNAME and all the arguments following the
        two dashes (--) are passed to the test binaries and thus to libtest
@@ -23,11 +23,14 @@ DESCRIPTION
 
            cargo test foo -- --test-threads 3
 
-       Tests are built with the --test option to rustc which creates an
-       executable with a main function that automatically runs all functions
-       annotated with the #[test] attribute in multiple threads. #[bench]
-       annotated functions will also be run with one iteration to verify that
-       they are functional.
+       Tests 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 in
+       multiple threads. #[bench] annotated functions will also be run with one
+       iteration to verify that they are functional.
+
+       If the package contains multiple test targets, each target compiles to a
+       special executable as aforementioned, and then is run serially.
 
        The libtest harness may be disabled by setting harness = false in the
        target manifest settings, in which case your code will need to provide

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

@@ -28,10 +28,11 @@ similarly named benchmarks like `foobar`):
 
     cargo bench -- foo --exact
 
-Benchmarks are built with the `--test` option to `rustc` which creates an
-executable with a `main` function that automatically runs all functions
-annotated with the `#[bench]` attribute. Cargo passes the `--bench` flag to
-the test harness to tell it to run only benchmarks.
+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.
 
 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/src/commands/cargo-test.md

@@ -12,7 +12,7 @@ cargo-test - Execute unit and integration tests of a package
 
 ## DESCRIPTION
 
-Compile and execute unit and integration tests.
+Compile and execute unit, integration, and documentation tests.
 
 The test filtering argument `TESTNAME` and all the arguments following the two
 dashes (`--`) are passed to the test binaries and thus to _libtest_ (rustc's
@@ -27,11 +27,14 @@ on 3 threads in parallel:
 
     cargo test foo -- --test-threads 3
 
-Tests are built with the `--test` option to `rustc` which creates an
-executable with a `main` function that automatically runs all functions
-annotated with the `#[test]` attribute in multiple threads. `#[bench]`
-annotated functions will also be run with one iteration to verify that they
-are functional.
+Tests 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 in multiple threads.
+`#[bench]` annotated functions will also be run with one iteration to verify
+that they are functional.
+
+If the package contains multiple test targets, each target compiles to a
+special executable as aforementioned, and then is run serially.
 
 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/etc/man/cargo-bench.1

@@ -28,10 +28,11 @@ cargo bench \-\- foo \-\-exact
 .fi
 .RE
 .sp
-Benchmarks are built with the \fB\-\-test\fR option to \fBrustc\fR which creates an
-executable with a \fBmain\fR function that automatically runs all functions
-annotated with the \fB#[bench]\fR attribute. Cargo passes the \fB\-\-bench\fR flag to
-the test harness to tell it to run only benchmarks.
+Benchmarks are built with the \fB\-\-test\fR option to \fBrustc\fR which creates a
+special executable by linking your code with libtest. The executable
+automatically runs all functions annotated with the \fB#[test]\fR attribute.
+Cargo passes the \fB\-\-bench\fR flag to the test harness to tell it to run only 
+benchmarks.
 .sp
 The libtest harness may be disabled by setting \fBharness = false\fR in the target
 manifest settings, in which case your code will need to provide its own \fBmain\fR

src/etc/man/cargo-test.1

@@ -8,7 +8,7 @@ cargo\-test \- Execute unit and integration tests of a package
 .SH "SYNOPSIS"
 \fBcargo test\fR [\fIoptions\fR] [\fItestname\fR] [\fB\-\-\fR \fItest\-options\fR]
 .SH "DESCRIPTION"
-Compile and execute unit and integration tests.
+Compile and execute unit, integration, and documentation tests.
 .sp
 The test filtering argument \fBTESTNAME\fR and all the arguments following the two
 dashes (\fB\-\-\fR) are passed to the test binaries and thus to \fIlibtest\fR (rustc's
@@ -27,11 +27,14 @@ cargo test foo \-\- \-\-test\-threads 3
 .fi
 .RE
 .sp
-Tests are built with the \fB\-\-test\fR option to \fBrustc\fR which creates an
-executable with a \fBmain\fR function that automatically runs all functions
-annotated with the \fB#[test]\fR attribute in multiple threads. \fB#[bench]\fR
-annotated functions will also be run with one iteration to verify that they
-are functional.
+Tests are built with the \fB\-\-test\fR option to \fBrustc\fR which creates a special
+executable by linking your code with libtest. The executable automatically
+runs all functions annotated with the \fB#[test]\fR attribute in multiple threads.
+\fB#[bench]\fR annotated functions will also be run with one iteration to verify
+that they are functional.
+.sp
+If the package contains multiple test targets, each target compiles to a
+special executable as aforementioned, and then is run serially.
 .sp
 The libtest harness may be disabled by setting \fBharness = false\fR in the target
 manifest settings, in which case your code will need to provide its own \fBmain\fR