Auto merge of #6481 - ehuss:man-update, r=alexcrichton

Some minor documentation changes.

A few updates for things that changed recently, some things that were
wrong/missing, and hopefully some clarifications on some matters.

For reviewing, I recommend ignoring the auto-generated .html/.man files and focus on the .md/.adoc files.

src/doc/man/cargo-bench.adoc

@@ -29,10 +29,12 @@ like `foobar`):
 
 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. 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
-benchmarks.
+annotated with the `#[bench]` 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`
+function to handle running benchmarks.
 
 == OPTIONS
 
@@ -49,7 +51,7 @@ include::options-packages.adoc[]
 When no target selection options are given, `cargo bench` will build the
 following targets of the selected packages:
 
-- lib – used to link with binaries and benchmarks
+- lib — used to link with binaries and benchmarks
 - bins (only if benchmark targets are built and required features are
   available)
 - lib as a benchmark

src/doc/man/cargo-install.adoc

@@ -98,7 +98,7 @@ include::options-features.adoc[]
 include::options-target-triple.adoc[]
 
 *--debug*::
-    Build in debug mode instead of release mode.
+    Build with the `dev` profile instead the `release` profile.
 
 === Miscellaneous Options
 

src/doc/man/cargo-login.adoc

@@ -13,7 +13,7 @@ cargo-login - Save an API token from the registry locally
 == DESCRIPTION
 
 This command will save the API token to disk so that commands that require
-authentication (such as man:cargo-publish[1]) will be automatically
+authentication, such as man:cargo-publish[1], will be automatically
 authenticated. The token is saved in `$CARGO_HOME/credentials`. `CARGO_HOME`
 defaults to `.cargo` in your home directory.
 
@@ -27,10 +27,6 @@ Take care to keep the token secret, it should not be shared with anyone else.
 
 === Login Options
 
-*--host* _HOST_::
-    Host to set the token for. This option does not affect the behavior of the
-    login command, and only affects the message displayed.
-
 include::options-registry.adoc[]
 
 === Display Options

src/doc/man/cargo-test.adoc

@@ -28,13 +28,18 @@ output of `cargo test -- --help`.  As an example, this will run all tests with
 
 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. 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.
+annotated with the `\#[test]` attribute in multiple threads. `#[bench]`
+annotated functions will also be run with one iteration to verify that they
+are functional.
+
+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 are also run by default, which is handled by `rustdoc`. It
-extracts code samples from documentation comments and executes them.
+extracts code samples from documentation comments and executes them. See the
+link:https://doc.rust-lang.org/rustdoc/[rustdoc book] for more information on
+writing doc tests.
 
 == OPTIONS
 
@@ -51,10 +56,10 @@ include::options-packages.adoc[]
 When no target selection options are given, `cargo test` will build the
 following targets of the selected packages:
 
-- lib – used to link with binaries, examples, integration tests, and doc tests
+- lib — used to link with binaries, examples, integration tests, and doc tests
 - bins (only if integration tests are built and required features are
   available)
-- examples – to ensure they compile
+- examples — to ensure they compile
 - lib as a unit test
 - bins as unit tests
 - integration tests

src/doc/man/cargo-update.adoc

@@ -42,6 +42,9 @@ If `-p` is not specified, all dependencies are updated.
     set the package to. If the package comes from a git repository, this can
     be a git revision (such as a SHA hash or tag).
 
+*--dry-run*::
+    Displays what would be updated, but doesn't actually write the lockfile.
+
 === Display Options
 
 include::options-display.adoc[]

src/doc/man/generated/cargo-bench.html

@@ -34,10 +34,13 @@ <h2 id="cargo_bench_description">DESCRIPTION</h2>
 <div class="paragraph">
 <p>Benchmarks are built with the <code>--test</code> option to <code>rustc</code> which creates an
 executable with a <code>main</code> function that automatically runs all functions
-annotated with the <code>#[bench]</code> attribute. The libtest harness may be disabled
-by setting <code>harness = false</code> in the target manifest settings, in which case
-your code will need to provide its own <code>main</code> function to handle running
-benchmarks.</p>
+annotated with the <code>#[bench]</code> attribute. Cargo passes the <code>--bench</code> flag to
+the test harness to tell it to run only benchmarks.</p>
+</div>
+<div class="paragraph">
+<p>The libtest harness may be disabled by setting <code>harness = false</code> in the target
+manifest settings, in which case your code will need to provide its own <code>main</code>
+function to handle running benchmarks.</p>
 </div>
 </div>
 </div>
@@ -101,7 +104,7 @@ <h3 id="cargo_bench_target_selection">Target Selection</h3>
 <div class="ulist">
 <ul>
 <li>
-<p>lib – used to link with binaries and benchmarks</p>
+<p>lib — used to link with binaries and benchmarks</p>
 </li>
 <li>
 <p>bins (only if benchmark targets are built and required features are
@@ -159,26 +162,32 @@ <h3 id="cargo_bench_target_selection">Target Selection</h3>
 </dd>
 <dt class="hdlist1"><strong>--tests</strong></dt>
 <dd>
-<p>Benchmark all tests. This includes both unit tests for libraries and binaries
-and integration tests. Targets may be disabled by setting <code>test = false</code>
-in the manifest settings for the target. Targets (such as examples) may be
-explicitly included by setting <code>test = true</code> in the target settings.</p>
+<p>Benchmark all targets in test mode that have the <code>test = true</code> manifest
+flag set. By default this includes the library and binaries built as
+unittests, and integration tests. Be aware that this will also build any
+required dependencies, so the lib target may be built twice (once as a
+unittest, and once as a dependency for binaries, integration tests, etc.).
+Targets may be enabled or disabled by setting the <code>test</code> flag in the
+manifest settings for the target.</p>
 </dd>
 <dt class="hdlist1"><strong>--bench</strong> <em>NAME</em>&#8230;&#8203;</dt>
 <dd>
 <p>Benchmark the specified benchmark. This flag may be specified multiple times.</p>
 </dd>
 <dt class="hdlist1"><strong>--benches</strong></dt>
 <dd>
-<p>Benchmark all benchmarks. This includes both unit benchmarks for libraries and
-binaries and bench targets. Targets may be disabled by setting <code>bench =
-false</code> in the manifest settings for the target. Targets (such as examples)
-may be explicitly included by setting <code>bench = true</code> in the target
-settings.</p>
+<p>Benchmark all targets in benchmark mode that have the <code>bench = true</code>
+manifest flag set. By default this includes the library and binaries built
+as benchmarks, and bench targets. Be aware that this will also build any
+required dependencies, so the lib target may be built twice (once as a
+benchmark, and once as a dependency for binaries, benchmarks, etc.).
+Targets may be enabled or disabled by setting the <code>bench</code> flag in the
+manifest settings for the target.</p>
 </dd>
 <dt class="hdlist1"><strong>--all-targets</strong></dt>
 <dd>
-<p>Benchmark all targets.</p>
+<p>Benchmark all targets. This is equivalent to specifying <code>--lib --bins
+--tests --benches --examples</code>.</p>
 </dd>
 </dl>
 </div>
@@ -215,44 +224,14 @@ <h3 id="cargo_bench_compilation_options">Compilation Options</h3>
 <dl>
 <dt class="hdlist1"><strong>--target</strong> <em>TRIPLE</em></dt>
 <dd>
-<p>Benchmark for the given architecture. The default is the host architecture.</p>
-<div class="paragraph">
-<p>The general format of the triple is <code>&lt;arch&gt;&lt;sub&gt;-&lt;vendor&gt;-&lt;sys&gt;-&lt;abi&gt;</code> where:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><code>arch</code> = The base CPU architecture, for example <code>x86_64</code>, <code>i686</code>, <code>arm</code>,
-<code>thumb</code>, <code>mips</code>, etc.</p>
-</li>
-<li>
-<p><code>sub</code> = The CPU sub-architecture, for example <code>arm</code> has <code>v7</code>, <code>v7s</code>, <code>v5te</code>,
-etc.</p>
-</li>
-<li>
-<p><code>vendor</code> = The vendor, for example <code>unknown</code>, <code>apple</code>, <code>pc</code>, <code>linux</code>, etc.</p>
-</li>
-<li>
-<p><code>sys</code> = The system name, for example <code>linux</code>, <code>windows</code>, etc. <code>none</code> is
-typically used for bare-metal without an OS.</p>
-</li>
-<li>
-<p><code>abi</code> = The ABI, for example <code>gnu</code>, <code>android</code>, <code>eabi</code>, etc.</p>
-</li>
-</ul>
-</div>
-<div class="openblock">
-<div class="content">
-<div class="paragraph">
-<p>Some parameters may be omitted. Run <code>rustc --print target-list</code> for a list of
-supported targets.</p>
-</div>
+<p>Benchmark for the given architecture. The default is the host
+architecture. The general format of the triple is
+<code>&lt;arch&gt;&lt;sub&gt;-&lt;vendor&gt;-&lt;sys&gt;-&lt;abi&gt;</code>. Run <code>rustc --print target-list</code> for a
+list of supported targets.</p>
 <div class="paragraph">
 <p>This may also be specified with the <code>build.target</code>
 <a href="reference/config.html">config value</a>.</p>
 </div>
-</div>
-</div>
 </dd>
 </dl>
 </div>

src/doc/man/generated/cargo-build.html

@@ -91,26 +91,32 @@ <h3 id="cargo_build_target_selection">Target Selection</h3>
 </dd>
 <dt class="hdlist1"><strong>--tests</strong></dt>
 <dd>
-<p>Build all tests. This includes both unit tests for libraries and binaries
-and integration tests. Targets may be disabled by setting <code>test = false</code>
-in the manifest settings for the target. Targets (such as examples) may be
-explicitly included by setting <code>test = true</code> in the target settings.</p>
+<p>Build all targets in test mode that have the <code>test = true</code> manifest
+flag set. By default this includes the library and binaries built as
+unittests, and integration tests. Be aware that this will also build any
+required dependencies, so the lib target may be built twice (once as a
+unittest, and once as a dependency for binaries, integration tests, etc.).
+Targets may be enabled or disabled by setting the <code>test</code> flag in the
+manifest settings for the target.</p>
 </dd>
 <dt class="hdlist1"><strong>--bench</strong> <em>NAME</em>&#8230;&#8203;</dt>
 <dd>
 <p>Build the specified benchmark. This flag may be specified multiple times.</p>
 </dd>
 <dt class="hdlist1"><strong>--benches</strong></dt>
 <dd>
-<p>Build all benchmarks. This includes both unit benchmarks for libraries and
-binaries and bench targets. Targets may be disabled by setting <code>bench =
-false</code> in the manifest settings for the target. Targets (such as examples)
-may be explicitly included by setting <code>bench = true</code> in the target
-settings.</p>
+<p>Build all targets in benchmark mode that have the <code>bench = true</code>
+manifest flag set. By default this includes the library and binaries built
+as benchmarks, and bench targets. Be aware that this will also build any
+required dependencies, so the lib target may be built twice (once as a
+benchmark, and once as a dependency for binaries, benchmarks, etc.).
+Targets may be enabled or disabled by setting the <code>bench</code> flag in the
+manifest settings for the target.</p>
 </dd>
 <dt class="hdlist1"><strong>--all-targets</strong></dt>
 <dd>
-<p>Build all targets.</p>
+<p>Build all targets. This is equivalent to specifying <code>--lib --bins
+--tests --benches --examples</code>.</p>
 </dd>
 </dl>
 </div>
@@ -147,48 +153,18 @@ <h3 id="cargo_build_compilation_options">Compilation Options</h3>
 <dl>
 <dt class="hdlist1"><strong>--target</strong> <em>TRIPLE</em></dt>
 <dd>
-<p>Build for the given architecture. The default is the host architecture.</p>
-<div class="paragraph">
-<p>The general format of the triple is <code>&lt;arch&gt;&lt;sub&gt;-&lt;vendor&gt;-&lt;sys&gt;-&lt;abi&gt;</code> where:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><code>arch</code> = The base CPU architecture, for example <code>x86_64</code>, <code>i686</code>, <code>arm</code>,
-<code>thumb</code>, <code>mips</code>, etc.</p>
-</li>
-<li>
-<p><code>sub</code> = The CPU sub-architecture, for example <code>arm</code> has <code>v7</code>, <code>v7s</code>, <code>v5te</code>,
-etc.</p>
-</li>
-<li>
-<p><code>vendor</code> = The vendor, for example <code>unknown</code>, <code>apple</code>, <code>pc</code>, <code>linux</code>, etc.</p>
-</li>
-<li>
-<p><code>sys</code> = The system name, for example <code>linux</code>, <code>windows</code>, etc. <code>none</code> is
-typically used for bare-metal without an OS.</p>
-</li>
-<li>
-<p><code>abi</code> = The ABI, for example <code>gnu</code>, <code>android</code>, <code>eabi</code>, etc.</p>
-</li>
-</ul>
-</div>
-<div class="openblock">
-<div class="content">
-<div class="paragraph">
-<p>Some parameters may be omitted. Run <code>rustc --print target-list</code> for a list of
-supported targets.</p>
-</div>
+<p>Build for the given architecture. The default is the host
+architecture. The general format of the triple is
+<code>&lt;arch&gt;&lt;sub&gt;-&lt;vendor&gt;-&lt;sys&gt;-&lt;abi&gt;</code>. Run <code>rustc --print target-list</code> for a
+list of supported targets.</p>
 <div class="paragraph">
 <p>This may also be specified with the <code>build.target</code>
 <a href="reference/config.html">config value</a>.</p>
 </div>
-</div>
-</div>
 </dd>
 <dt class="hdlist1"><strong>--release</strong></dt>
 <dd>
-<p>Build artifacts in release mode, with optimizations. See the
+<p>Build optimized artifacts with the <code>release</code> profile. See the
 <a href="#cargo_build_profiles">PROFILES</a> section for details on how this affects profile selection.</p>
 </dd>
 </dl>
@@ -356,11 +332,11 @@ <h2 id="cargo_build_profiles">PROFILES</h2>
 <code>dev</code> or <code>test</code> profiles are used. If the <code>--release</code> flag is given, then the
 <code>release</code> or <code>bench</code> profiles are used.</p>
 </div>
-<table class="tableblock frame-all grid-all stretch">
+<table class="tableblock frame-all grid-all fit-content">
 <colgroup>
-<col style="width: 33.3333%;">
-<col style="width: 33.3333%;">
-<col style="width: 33.3334%;">
+<col>
+<col>
+<col>
 </colgroup>
 <thead>
 <tr>
@@ -376,7 +352,8 @@ <h2 id="cargo_build_profiles">PROFILES</h2>
 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>release</code></p></td>
 </tr>
 <tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">test, bench</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">test, bench, or any target<br>
+ in "test" or "bench" mode</p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>test</code></p></td>
 <td class="tableblock halign-left valign-top"><p class="tableblock"><code>bench</code></p></td>
 </tr>