Improve keep-going docs

Author: dtolnay

src/doc/man/cargo-bench.md

@@ -157,9 +157,16 @@ Rust test harness runs benchmarks serially in a single thread.
 
 {{#options}}
 {{> options-jobs }}
-{{> options-keep-going }}
 {{/options}}
 
+While `cargo bench` involves compilation, it does not provide a `--keep-going`
+flag. Use `--no-fail-fast` to run as many benchmarks as possible without
+stopping at the first failure. To "compile" as many benchmarks as possible, use
+`--benches` to build benchmark binaries separately. For example:
+
+    cargo build --benches --release --keep-going
+    cargo bench --no-fail-fast
+
 {{> section-environment }}
 
 {{> section-exit-status }}

src/doc/man/cargo-test.md

@@ -190,6 +190,14 @@ includes an option to control the number of threads used:
 
 {{/options}}
 
+While `cargo test` involves compilation, it does not provide a `--keep-going`
+flag. Use `--no-fail-fast` to run as many tests as possible without stopping at
+the first failure. To "compile" as many tests as possible, use `--tests` to
+build test binaries separately. For example:
+
+    cargo build --tests --keep-going
+    cargo test --tests --no-fail-fast
+
 {{> section-environment }}
 
 {{> section-exit-status }}

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

@@ -413,9 +413,14 @@ OPTIONS
            If a string default is provided, it sets the value back to defaults.
            Should not be 0.
 
-       --keep-going
-           Build as many crates in the dependency graph as possible, rather
-           than aborting the build on the first one that fails to build.
+       While cargo bench involves compilation, it does not provide a
+       --keep-going flag. Use --no-fail-fast to run as many benchmarks as
+       possible without stopping at the first failure. To “compile” as many
+       benchmarks as possible, use --benches to build benchmark binaries
+       separately. For example:
+
+           cargo build --benches --release --keep-going
+           cargo bench --no-fail-fast
 
 ENVIRONMENT
        See the reference

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

@@ -348,6 +348,13 @@ OPTIONS
            Build as many crates in the dependency graph as possible, rather
            than aborting the build on the first one that fails to build.
 
+           For example if the current package depends on dependencies fails and
+           works, one of which fails to build, cargo check -j1 may or may not
+           build the one that succeeds (depending on which one of the two
+           builds Cargo picked to run first), whereas cargo check -j1
+           --keep-going would definitely run both builds, even if the one run
+           first fails.
+
        --future-incompat-report
            Displays a future-incompat report for any future-incompatible
            warnings produced during execution of this command

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

@@ -333,6 +333,13 @@ OPTIONS
            Build as many crates in the dependency graph as possible, rather
            than aborting the build on the first one that fails to build.
 
+           For example if the current package depends on dependencies fails and
+           works, one of which fails to build, cargo check -j1 may or may not
+           build the one that succeeds (depending on which one of the two
+           builds Cargo picked to run first), whereas cargo check -j1
+           --keep-going would definitely run both builds, even if the one run
+           first fails.
+
        --future-incompat-report
            Displays a future-incompat report for any future-incompatible
            warnings produced during execution of this command

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

@@ -304,6 +304,13 @@ OPTIONS
            Build as many crates in the dependency graph as possible, rather
            than aborting the build on the first one that fails to build.
 
+           For example if the current package depends on dependencies fails and
+           works, one of which fails to build, cargo check -j1 may or may not
+           build the one that succeeds (depending on which one of the two
+           builds Cargo picked to run first), whereas cargo check -j1
+           --keep-going would definitely run both builds, even if the one run
+           first fails.
+
 ENVIRONMENT
        See the reference
        <https://doc.rust-lang.org/cargo/reference/environment-variables.html>

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

@@ -406,6 +406,13 @@ OPTIONS
            Build as many crates in the dependency graph as possible, rather
            than aborting the build on the first one that fails to build.
 
+           For example if the current package depends on dependencies fails and
+           works, one of which fails to build, cargo check -j1 may or may not
+           build the one that succeeds (depending on which one of the two
+           builds Cargo picked to run first), whereas cargo check -j1
+           --keep-going would definitely run both builds, even if the one run
+           first fails.
+
 ENVIRONMENT
        See the reference
        <https://doc.rust-lang.org/cargo/reference/environment-variables.html>

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

@@ -281,6 +281,13 @@ OPTIONS
            Build as many crates in the dependency graph as possible, rather
            than aborting the build on the first one that fails to build.
 
+           For example if the current package depends on dependencies fails and
+           works, one of which fails to build, cargo check -j1 may or may not
+           build the one that succeeds (depending on which one of the two
+           builds Cargo picked to run first), whereas cargo check -j1
+           --keep-going would definitely run both builds, even if the one run
+           first fails.
+
    Display Options
        -v, --verbose
            Use verbose output. May be specified twice for “very verbose”

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

@@ -198,6 +198,13 @@ OPTIONS
            Build as many crates in the dependency graph as possible, rather
            than aborting the build on the first one that fails to build.
 
+           For example if the current package depends on dependencies fails and
+           works, one of which fails to build, cargo check -j1 may or may not
+           build the one that succeeds (depending on which one of the two
+           builds Cargo picked to run first), whereas cargo check -j1
+           --keep-going would definitely run both builds, even if the one run
+           first fails.
+
    Display Options
        -v, --verbose
            Use verbose output. May be specified twice for “very verbose”

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

@@ -164,6 +164,13 @@ OPTIONS
            Build as many crates in the dependency graph as possible, rather
            than aborting the build on the first one that fails to build.
 
+           For example if the current package depends on dependencies fails and
+           works, one of which fails to build, cargo check -j1 may or may not
+           build the one that succeeds (depending on which one of the two
+           builds Cargo picked to run first), whereas cargo check -j1
+           --keep-going would definitely run both builds, even if the one run
+           first fails.
+
    Display Options
        -v, --verbose
            Use verbose output. May be specified twice for “very verbose”

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

@@ -252,6 +252,13 @@ OPTIONS
            Build as many crates in the dependency graph as possible, rather
            than aborting the build on the first one that fails to build.
 
+           For example if the current package depends on dependencies fails and
+           works, one of which fails to build, cargo check -j1 may or may not
+           build the one that succeeds (depending on which one of the two
+           builds Cargo picked to run first), whereas cargo check -j1
+           --keep-going would definitely run both builds, even if the one run
+           first fails.
+
 ENVIRONMENT
        See the reference
        <https://doc.rust-lang.org/cargo/reference/environment-variables.html>

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

@@ -350,6 +350,13 @@ OPTIONS
            Build as many crates in the dependency graph as possible, rather
            than aborting the build on the first one that fails to build.
 
+           For example if the current package depends on dependencies fails and
+           works, one of which fails to build, cargo check -j1 may or may not
+           build the one that succeeds (depending on which one of the two
+           builds Cargo picked to run first), whereas cargo check -j1
+           --keep-going would definitely run both builds, even if the one run
+           first fails.
+
        --future-incompat-report
            Displays a future-incompat report for any future-incompatible
            warnings produced during execution of this command

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

@@ -320,6 +320,13 @@ OPTIONS
            Build as many crates in the dependency graph as possible, rather
            than aborting the build on the first one that fails to build.
 
+           For example if the current package depends on dependencies fails and
+           works, one of which fails to build, cargo check -j1 may or may not
+           build the one that succeeds (depending on which one of the two
+           builds Cargo picked to run first), whereas cargo check -j1
+           --keep-going would definitely run both builds, even if the one run
+           first fails.
+
 ENVIRONMENT
        See the reference
        <https://doc.rust-lang.org/cargo/reference/environment-variables.html>

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

@@ -448,6 +448,14 @@ OPTIONS
 
            See cargo-report(1)
 
+       While cargo test involves compilation, it does not provide a
+       --keep-going flag. Use --no-fail-fast to run as many tests as possible
+       without stopping at the first failure. To “compile” as many tests as
+       possible, use --tests to build test binaries separately. For example:
+
+           cargo build --tests --keep-going
+           cargo test --tests --no-fail-fast
+
 ENVIRONMENT
        See the reference
        <https://doc.rust-lang.org/cargo/reference/environment-variables.html>

src/doc/man/includes/options-keep-going.md

@@ -1,4 +1,10 @@
 {{#option "`--keep-going`"}}
 Build as many crates in the dependency graph as possible, rather than aborting
 the build on the first one that fails to build.
+
+For example if the current package depends on dependencies `fails` and `works`,
+one of which fails to build, `cargo check -j1` may or may not build the one that
+succeeds (depending on which one of the two builds Cargo picked to run first),
+whereas `cargo check -j1 --keep-going` would definitely run both builds, even if
+the one run first fails.
 {{/option}}

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

@@ -481,12 +481,15 @@ a string <code>default</code> is provided, it sets the value back to defaults.
 Should not be 0.</dd>
 
 
-<dt class="option-term" id="option-cargo-bench---keep-going"><a class="option-anchor" href="#option-cargo-bench---keep-going"></a><code>--keep-going</code></dt>
-<dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting
-the build on the first one that fails to build.</dd>
+</dl>
 
+While `cargo bench` involves compilation, it does not provide a `--keep-going`
+flag. Use `--no-fail-fast` to run as many benchmarks as possible without
+stopping at the first failure. To "compile" as many benchmarks as possible, use
+`--benches` to build benchmark binaries separately. For example:
 
-</dl>
+    cargo build --benches --release --keep-going
+    cargo bench --no-fail-fast
 
 ## ENVIRONMENT
 

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

@@ -409,7 +409,12 @@ Should not be 0.</dd>
 
 <dt class="option-term" id="option-cargo-build---keep-going"><a class="option-anchor" href="#option-cargo-build---keep-going"></a><code>--keep-going</code></dt>
 <dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting
-the build on the first one that fails to build.</dd>
+the build on the first one that fails to build.</p>
+<p>For example if the current package depends on dependencies <code>fails</code> and <code>works</code>,
+one of which fails to build, <code>cargo check -j1</code> may or may not build the one that
+succeeds (depending on which one of the two builds Cargo picked to run first),
+whereas <code>cargo check -j1 --keep-going</code> would definitely run both builds, even if
+the one run first fails.</dd>
 
 
 <dt class="option-term" id="option-cargo-build---future-incompat-report"><a class="option-anchor" href="#option-cargo-build---future-incompat-report"></a><code>--future-incompat-report</code></dt>

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

@@ -390,7 +390,12 @@ Should not be 0.</dd>
 
 <dt class="option-term" id="option-cargo-check---keep-going"><a class="option-anchor" href="#option-cargo-check---keep-going"></a><code>--keep-going</code></dt>
 <dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting
-the build on the first one that fails to build.</dd>
+the build on the first one that fails to build.</p>
+<p>For example if the current package depends on dependencies <code>fails</code> and <code>works</code>,
+one of which fails to build, <code>cargo check -j1</code> may or may not build the one that
+succeeds (depending on which one of the two builds Cargo picked to run first),
+whereas <code>cargo check -j1 --keep-going</code> would definitely run both builds, even if
+the one run first fails.</dd>
 
 
 <dt class="option-term" id="option-cargo-check---future-incompat-report"><a class="option-anchor" href="#option-cargo-check---future-incompat-report"></a><code>--future-incompat-report</code></dt>

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

@@ -364,7 +364,12 @@ Should not be 0.</dd>
 
 <dt class="option-term" id="option-cargo-doc---keep-going"><a class="option-anchor" href="#option-cargo-doc---keep-going"></a><code>--keep-going</code></dt>
 <dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting
-the build on the first one that fails to build.</dd>
+the build on the first one that fails to build.</p>
+<p>For example if the current package depends on dependencies <code>fails</code> and <code>works</code>,
+one of which fails to build, <code>cargo check -j1</code> may or may not build the one that
+succeeds (depending on which one of the two builds Cargo picked to run first),
+whereas <code>cargo check -j1 --keep-going</code> would definitely run both builds, even if
+the one run first fails.</dd>
 
 
 </dl>

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

@@ -470,7 +470,12 @@ Should not be 0.</dd>
 
 <dt class="option-term" id="option-cargo-fix---keep-going"><a class="option-anchor" href="#option-cargo-fix---keep-going"></a><code>--keep-going</code></dt>
 <dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting
-the build on the first one that fails to build.</dd>
+the build on the first one that fails to build.</p>
+<p>For example if the current package depends on dependencies <code>fails</code> and <code>works</code>,
+one of which fails to build, <code>cargo check -j1</code> may or may not build the one that
+succeeds (depending on which one of the two builds Cargo picked to run first),
+whereas <code>cargo check -j1 --keep-going</code> would definitely run both builds, even if
+the one run first fails.</dd>
 
 
 </dl>

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

@@ -319,7 +319,12 @@ Should not be 0.</dd>
 
 <dt class="option-term" id="option-cargo-install---keep-going"><a class="option-anchor" href="#option-cargo-install---keep-going"></a><code>--keep-going</code></dt>
 <dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting
-the build on the first one that fails to build.</dd>
+the build on the first one that fails to build.</p>
+<p>For example if the current package depends on dependencies <code>fails</code> and <code>works</code>,
+one of which fails to build, <code>cargo check -j1</code> may or may not build the one that
+succeeds (depending on which one of the two builds Cargo picked to run first),
+whereas <code>cargo check -j1 --keep-going</code> would definitely run both builds, even if
+the one run first fails.</dd>
 
 
 </dl>

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

@@ -234,7 +234,12 @@ Should not be 0.</dd>
 
 <dt class="option-term" id="option-cargo-package---keep-going"><a class="option-anchor" href="#option-cargo-package---keep-going"></a><code>--keep-going</code></dt>
 <dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting
-the build on the first one that fails to build.</dd>
+the build on the first one that fails to build.</p>
+<p>For example if the current package depends on dependencies <code>fails</code> and <code>works</code>,
+one of which fails to build, <code>cargo check -j1</code> may or may not build the one that
+succeeds (depending on which one of the two builds Cargo picked to run first),
+whereas <code>cargo check -j1 --keep-going</code> would definitely run both builds, even if
+the one run first fails.</dd>
 
 
 </dl>

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

@@ -200,7 +200,12 @@ Should not be 0.</dd>
 
 <dt class="option-term" id="option-cargo-publish---keep-going"><a class="option-anchor" href="#option-cargo-publish---keep-going"></a><code>--keep-going</code></dt>
 <dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting
-the build on the first one that fails to build.</dd>
+the build on the first one that fails to build.</p>
+<p>For example if the current package depends on dependencies <code>fails</code> and <code>works</code>,
+one of which fails to build, <code>cargo check -j1</code> may or may not build the one that
+succeeds (depending on which one of the two builds Cargo picked to run first),
+whereas <code>cargo check -j1 --keep-going</code> would definitely run both builds, even if
+the one run first fails.</dd>
 
 
 </dl>

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

@@ -306,7 +306,12 @@ Should not be 0.</dd>
 
 <dt class="option-term" id="option-cargo-run---keep-going"><a class="option-anchor" href="#option-cargo-run---keep-going"></a><code>--keep-going</code></dt>
 <dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting
-the build on the first one that fails to build.</dd>
+the build on the first one that fails to build.</p>
+<p>For example if the current package depends on dependencies <code>fails</code> and <code>works</code>,
+one of which fails to build, <code>cargo check -j1</code> may or may not build the one that
+succeeds (depending on which one of the two builds Cargo picked to run first),
+whereas <code>cargo check -j1 --keep-going</code> would definitely run both builds, even if
+the one run first fails.</dd>
 
 
 </dl>

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

@@ -403,7 +403,12 @@ Should not be 0.</dd>
 
 <dt class="option-term" id="option-cargo-rustc---keep-going"><a class="option-anchor" href="#option-cargo-rustc---keep-going"></a><code>--keep-going</code></dt>
 <dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting
-the build on the first one that fails to build.</dd>
+the build on the first one that fails to build.</p>
+<p>For example if the current package depends on dependencies <code>fails</code> and <code>works</code>,
+one of which fails to build, <code>cargo check -j1</code> may or may not build the one that
+succeeds (depending on which one of the two builds Cargo picked to run first),
+whereas <code>cargo check -j1 --keep-going</code> would definitely run both builds, even if
+the one run first fails.</dd>
 
 
 <dt class="option-term" id="option-cargo-rustc---future-incompat-report"><a class="option-anchor" href="#option-cargo-rustc---future-incompat-report"></a><code>--future-incompat-report</code></dt>

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

@@ -383,7 +383,12 @@ Should not be 0.</dd>
 
 <dt class="option-term" id="option-cargo-rustdoc---keep-going"><a class="option-anchor" href="#option-cargo-rustdoc---keep-going"></a><code>--keep-going</code></dt>
 <dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting
-the build on the first one that fails to build.</dd>
+the build on the first one that fails to build.</p>
+<p>For example if the current package depends on dependencies <code>fails</code> and <code>works</code>,
+one of which fails to build, <code>cargo check -j1</code> may or may not build the one that
+succeeds (depending on which one of the two builds Cargo picked to run first),
+whereas <code>cargo check -j1 --keep-going</code> would definitely run both builds, even if
+the one run first fails.</dd>
 
 
 </dl>