doc: execution model of doctest

NOTE: This is an undocumented implementation details.

Author: weihanglo

src/doc/man/cargo-test.md

@@ -40,10 +40,21 @@ 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`
 function to handle running tests.
 
+### Documentation tests
+
 Documentation tests are also run by default, which is handled by `rustdoc`. It
 extracts code samples from documentation comments of the library target, and
-then executes them. See the [rustdoc book](https://doc.rust-lang.org/rustdoc/)
-for more information on writing doc tests.
+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
+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.
+
+See the [rustdoc book](https://doc.rust-lang.org/rustdoc/) for more information
+on writing doc tests.
 
 ## OPTIONS
 

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

@@ -36,11 +36,21 @@ DESCRIPTION
        target manifest settings, in which case your code will need to provide
        its own main function to handle running tests.
 
+   Documentation tests
        Documentation tests are also run by default, which is handled by
        rustdoc. It extracts code samples from documentation comments of the
-       library target, and then executes them. See the rustdoc book
-       <https://doc.rust-lang.org/rustdoc/> for more information on writing doc
-       tests.
+       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 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.
+
+       See the rustdoc book <https://doc.rust-lang.org/rustdoc/> for more
+       information on writing doc tests.
 
 OPTIONS
    Test Options

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

@@ -40,10 +40,21 @@ 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`
 function to handle running tests.
 
+### Documentation tests
+
 Documentation tests are also run by default, which is handled by `rustdoc`. It
 extracts code samples from documentation comments of the library target, and
-then executes them. See the [rustdoc book](https://doc.rust-lang.org/rustdoc/)
-for more information on writing doc tests.
+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
+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.
+
+See the [rustdoc book](https://doc.rust-lang.org/rustdoc/) for more information
+on writing doc tests.
 
 ## OPTIONS
 

src/doc/src/reference/cargo-targets.md

@@ -100,7 +100,12 @@ parallel, reporting the success and failure of each test. See [the `harness`
 field](#the-harness-field) if you want to use a different harness or test
 strategy.
 
+> There is another style of test in Cargo: [documentation tests][documentation examples].
+> They are handled by `rustdoc` and have a slightly different execution model.
+> For more information, please see [`cargo test`][cargo-test-documentation-tests].
+
 [libtest harness]: ../../rustc/tests/index.html
+[cargo-test-documentation-tests]: ../commands/cargo-test.md#documentation-tests
 
 #### Integration tests
 

src/etc/man/cargo-test.1

@@ -39,11 +39,20 @@ special executable as aforementioned, and then is run serially.
 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
 function to handle running tests.
-.sp
+.SS "Documentation tests"
 Documentation tests are also run by default, which is handled by \fBrustdoc\fR\&. It
 extracts code samples from documentation comments of the library target, and
-then executes them. See the \fIrustdoc book\fR <https://doc.rust\-lang.org/rustdoc/>
-for more information on writing doc tests.
+then executes them.
+.sp
+Different from normal test targets, each code block compiles to a doctest
+executable on the fly with \fBrustc\fR\&. These executables runs 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 \fB\-\-jobs\fR might not
+take effect. Note that this execution model of doctests is an undocumented
+implementation details, beware of depending on it.
+.sp
+See the \fIrustdoc book\fR <https://doc.rust\-lang.org/rustdoc/> for more information
+on writing doc tests.
 .SH "OPTIONS"
 .SS "Test Options"
 .sp