Auto merge of #7733 - ehuss:doc-updates, r=Eh2406

Various doc updates

This is a collection of documentation updates that have been in my todo list for a while. Each change is in a separate commit.

The "features" chapter will probably get significant changes in the future, as it is pretty bare right now. Similarly the "workspace" chapter could probably use more examples.

Closes #3062
Closes #3817
Closes #3971
Closes #4212
Closes #4438
Closes #4756
Closes #5822
Closes #6913
Closes #7055

src/doc/man/cargo-fix.adoc

@@ -28,14 +28,18 @@ executing:
 
     cargo fix --edition
 
-which behaves the same as `cargo check --all-targets`. Similarly if you'd like
-to fix code for different platforms you can do:
+which behaves the same as `cargo check --all-targets`.
 
-    cargo fix --edition --target x86_64-pc-windows-gnu
+`cargo fix` is only capable of fixing code that is normally compiled with
+`cargo check`. If code is conditionally enabled with optional features, you
+will need to enable those features for that code to be analyzed:
+
+    cargo fix --edition --features foo
 
-or if your crate has optional features:
+Similarly, other `cfg` expressions like platform-specific code will need to
+pass `--target` to fix code for the given target.
 
-    cargo fix --edition --no-default-features --features foo
+    cargo fix --edition --target x86_64-pc-windows-gnu
 
 If you encounter any problems with `cargo fix` or otherwise have any questions
 or feature requests please don't hesitate to file an issue at

src/doc/man/cargo-package.adoc

@@ -33,6 +33,9 @@ steps:
       about the current VCS checkout hash if available (not included with
       `--allow-dirty`).
 . Extract the `.crate` file and build it to verify it can build.
+    - This will rebuild your package from scratch to ensure that it can be
+      built from a pristine state. The `--no-verify` flag can be used to skip
+      this step.
 . Check that build scripts did not modify any source files.
 
 The list of files included can be controlled with the `include` and `exclude`

src/doc/man/cargo-rustc.adoc

@@ -25,8 +25,8 @@ flags.
 
 include::description-one-target.adoc[]
 To pass flags to all compiler processes spawned by Cargo, use the `RUSTFLAGS`
-environment variable or the `build.rustflags`
-linkcargo:reference/config.html[config value].
+linkcargo:reference/environment-variables.html[environment variable] or the
+`build.rustflags` linkcargo:reference/config.html[config value].
 
 == OPTIONS
 

src/doc/man/cargo-rustdoc.adoc

@@ -25,8 +25,8 @@ flags.
 
 include::description-one-target.adoc[]
 To pass flags to all rustdoc processes spawned by Cargo, use the
-`RUSTDOCFLAGS` environment variable or the `build.rustdocflags` configuration
-option.
+`RUSTDOCFLAGS` linkcargo:reference/environment-variables.html[environment variable]
+or the `build.rustdocflags` linkcargo:reference/config.html[config value].
 
 == OPTIONS
 

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

@@ -213,7 +213,8 @@ <h3 id="cargo_bench_feature_selection">Feature Selection</h3>
 <dd>
 <p>Space or comma separated list of features to activate. These features only
 apply to the current directory&#8217;s package. Features of direct dependencies
-may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
+may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax. This flag may be
+specified multiple times, which enables all specified features.</p>
 </dd>
 <dt class="hdlist1"><strong>--all-features</strong></dt>
 <dd>
@@ -241,6 +242,11 @@ <h3 id="cargo_bench_compilation_options">Compilation Options</h3>
 <p>This may also be specified with the <code>build.target</code>
 <a href="../reference/config.html">config value</a>.</p>
 </div>
+<div class="paragraph">
+<p>Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
+</div>
 </dd>
 </dl>
 </div>

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

@@ -142,7 +142,8 @@ <h3 id="cargo_build_feature_selection">Feature Selection</h3>
 <dd>
 <p>Space or comma separated list of features to activate. These features only
 apply to the current directory&#8217;s package. Features of direct dependencies
-may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
+may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax. This flag may be
+specified multiple times, which enables all specified features.</p>
 </dd>
 <dt class="hdlist1"><strong>--all-features</strong></dt>
 <dd>
@@ -170,6 +171,11 @@ <h3 id="cargo_build_compilation_options">Compilation Options</h3>
 <p>This may also be specified with the <code>build.target</code>
 <a href="../reference/config.html">config value</a>.</p>
 </div>
+<div class="paragraph">
+<p>Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
+</div>
 </dd>
 <dt class="hdlist1"><strong>--release</strong></dt>
 <dd>

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

@@ -146,7 +146,8 @@ <h3 id="cargo_check_feature_selection">Feature Selection</h3>
 <dd>
 <p>Space or comma separated list of features to activate. These features only
 apply to the current directory&#8217;s package. Features of direct dependencies
-may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
+may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax. This flag may be
+specified multiple times, which enables all specified features.</p>
 </dd>
 <dt class="hdlist1"><strong>--all-features</strong></dt>
 <dd>
@@ -174,6 +175,11 @@ <h3 id="cargo_check_compilation_options">Compilation Options</h3>
 <p>This may also be specified with the <code>build.target</code>
 <a href="../reference/config.html">config value</a>.</p>
 </div>
+<div class="paragraph">
+<p>Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
+</div>
 </dd>
 <dt class="hdlist1"><strong>--release</strong></dt>
 <dd>

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

@@ -73,6 +73,11 @@ <h3 id="cargo_clean_clean_options">Clean Options</h3>
 <p>This may also be specified with the <code>build.target</code>
 <a href="../reference/config.html">config value</a>.</p>
 </div>
+<div class="paragraph">
+<p>Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
+</div>
 </dd>
 </dl>
 </div>

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

@@ -124,7 +124,8 @@ <h3 id="cargo_doc_feature_selection">Feature Selection</h3>
 <dd>
 <p>Space or comma separated list of features to activate. These features only
 apply to the current directory&#8217;s package. Features of direct dependencies
-may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
+may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax. This flag may be
+specified multiple times, which enables all specified features.</p>
 </dd>
 <dt class="hdlist1"><strong>--all-features</strong></dt>
 <dd>
@@ -152,6 +153,11 @@ <h3 id="cargo_doc_compilation_options">Compilation Options</h3>
 <p>This may also be specified with the <code>build.target</code>
 <a href="../reference/config.html">config value</a>.</p>
 </div>
+<div class="paragraph">
+<p>Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
+</div>
 </dd>
 <dt class="hdlist1"><strong>--release</strong></dt>
 <dd>

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

@@ -50,6 +50,11 @@ <h3 id="cargo_fetch_fetch_options">Fetch options</h3>
 <p>This may also be specified with the <code>build.target</code>
 <a href="../reference/config.html">config value</a>.</p>
 </div>
+<div class="paragraph">
+<p>Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
+</div>
 </dd>
 </dl>
 </div>

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

@@ -34,20 +34,25 @@ <h2 id="cargo_fix_description">DESCRIPTION</h2>
 </div>
 </div>
 <div class="paragraph">
-<p>which behaves the same as <code>cargo check --all-targets</code>. Similarly if you&#8217;d like
-to fix code for different platforms you can do:</p>
+<p>which behaves the same as <code>cargo check --all-targets</code>.</p>
+</div>
+<div class="paragraph">
+<p><code>cargo fix</code> is only capable of fixing code that is normally compiled with
+<code>cargo check</code>. If code is conditionally enabled with optional features, you
+will need to enable those features for that code to be analyzed:</p>
 </div>
 <div class="literalblock">
 <div class="content">
-<pre>cargo fix --edition --target x86_64-pc-windows-gnu</pre>
+<pre>cargo fix --edition --features foo</pre>
 </div>
 </div>
 <div class="paragraph">
-<p>or if your crate has optional features:</p>
+<p>Similarly, other <code>cfg</code> expressions like platform-specific code will need to
+pass <code>--target</code> to fix code for the given target.</p>
 </div>
 <div class="literalblock">
 <div class="content">
-<pre>cargo fix --edition --no-default-features --features foo</pre>
+<pre>cargo fix --edition --target x86_64-pc-windows-gnu</pre>
 </div>
 </div>
 <div class="paragraph">
@@ -217,7 +222,8 @@ <h3 id="cargo_fix_feature_selection">Feature Selection</h3>
 <dd>
 <p>Space or comma separated list of features to activate. These features only
 apply to the current directory&#8217;s package. Features of direct dependencies
-may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
+may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax. This flag may be
+specified multiple times, which enables all specified features.</p>
 </dd>
 <dt class="hdlist1"><strong>--all-features</strong></dt>
 <dd>
@@ -245,6 +251,11 @@ <h3 id="cargo_fix_compilation_options">Compilation Options</h3>
 <p>This may also be specified with the <code>build.target</code>
 <a href="../reference/config.html">config value</a>.</p>
 </div>
+<div class="paragraph">
+<p>Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
+</div>
 </dd>
 <dt class="hdlist1"><strong>--release</strong></dt>
 <dd>

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

@@ -212,7 +212,8 @@ <h3 id="cargo_install_feature_selection">Feature Selection</h3>
 <dd>
 <p>Space or comma separated list of features to activate. These features only
 apply to the current directory&#8217;s package. Features of direct dependencies
-may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
+may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax. This flag may be
+specified multiple times, which enables all specified features.</p>
 </dd>
 <dt class="hdlist1"><strong>--all-features</strong></dt>
 <dd>
@@ -240,6 +241,11 @@ <h3 id="cargo_install_compilation_options">Compilation Options</h3>
 <p>This may also be specified with the <code>build.target</code>
 <a href="../reference/config.html">config value</a>.</p>
 </div>
+<div class="paragraph">
+<p>Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
+</div>
 </dd>
 <dt class="hdlist1"><strong>--debug</strong></dt>
 <dd>

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

@@ -321,7 +321,8 @@ <h3 id="cargo_metadata_feature_selection">Feature Selection</h3>
 <dd>
 <p>Space or comma separated list of features to activate. These features only
 apply to the current directory&#8217;s package. Features of direct dependencies
-may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
+may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax. This flag may be
+specified multiple times, which enables all specified features.</p>
 </dd>
 <dt class="hdlist1"><strong>--all-features</strong></dt>
 <dd>

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

@@ -59,6 +59,15 @@ <h2 id="cargo_package_description">DESCRIPTION</h2>
 </li>
 <li>
 <p>Extract the <code>.crate</code> file and build it to verify it can build.</p>
+<div class="ulist">
+<ul>
+<li>
+<p>This will rebuild your package from scratch to ensure that it can be
+built from a pristine state. The <code>--no-verify</code> flag can be used to skip
+this step.</p>
+</li>
+</ul>
+</div>
 </li>
 <li>
 <p>Check that build scripts did not modify any source files.</p>
@@ -117,6 +126,11 @@ <h3 id="cargo_package_compilation_options">Compilation Options</h3>
 <p>This may also be specified with the <code>build.target</code>
 <a href="../reference/config.html">config value</a>.</p>
 </div>
+<div class="paragraph">
+<p>Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
+</div>
 </dd>
 <dt class="hdlist1"><strong>--target-dir</strong> <em>DIRECTORY</em></dt>
 <dd>
@@ -140,7 +154,8 @@ <h3 id="cargo_package_feature_selection">Feature Selection</h3>
 <dd>
 <p>Space or comma separated list of features to activate. These features only
 apply to the current directory&#8217;s package. Features of direct dependencies
-may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
+may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax. This flag may be
+specified multiple times, which enables all specified features.</p>
 </dd>
 <dt class="hdlist1"><strong>--all-features</strong></dt>
 <dd>

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

@@ -110,6 +110,11 @@ <h3 id="cargo_publish_compilation_options">Compilation Options</h3>
 <p>This may also be specified with the <code>build.target</code>
 <a href="../reference/config.html">config value</a>.</p>
 </div>
+<div class="paragraph">
+<p>Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
+</div>
 </dd>
 <dt class="hdlist1"><strong>--target-dir</strong> <em>DIRECTORY</em></dt>
 <dd>
@@ -133,7 +138,8 @@ <h3 id="cargo_publish_feature_selection">Feature Selection</h3>
 <dd>
 <p>Space or comma separated list of features to activate. These features only
 apply to the current directory&#8217;s package. Features of direct dependencies
-may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
+may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax. This flag may be
+specified multiple times, which enables all specified features.</p>
 </dd>
 <dt class="hdlist1"><strong>--all-features</strong></dt>
 <dd>

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

@@ -76,7 +76,8 @@ <h3 id="cargo_run_feature_selection">Feature Selection</h3>
 <dd>
 <p>Space or comma separated list of features to activate. These features only
 apply to the current directory&#8217;s package. Features of direct dependencies
-may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
+may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax. This flag may be
+specified multiple times, which enables all specified features.</p>
 </dd>
 <dt class="hdlist1"><strong>--all-features</strong></dt>
 <dd>
@@ -104,6 +105,11 @@ <h3 id="cargo_run_compilation_options">Compilation Options</h3>
 <p>This may also be specified with the <code>build.target</code>
 <a href="../reference/config.html">config value</a>.</p>
 </div>
+<div class="paragraph">
+<p>Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
+</div>
 </dd>
 <dt class="hdlist1"><strong>--release</strong></dt>
 <dd>

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

@@ -31,8 +31,8 @@ <h2 id="cargo_rustc_description">DESCRIPTION</h2>
 package the filters of <code>--lib</code>, <code>--bin</code>, etc, must be used to select which
 target is compiled.
 To pass flags to all compiler processes spawned by Cargo, use the <code>RUSTFLAGS</code>
-environment variable or the <code>build.rustflags</code>
-<a href="../reference/config.html">config value</a>.</p>
+<a href="../reference/environment-variables.html">environment variable</a> or the
+<code>build.rustflags</code> <a href="../reference/config.html">config value</a>.</p>
 </div>
 </div>
 </div>
@@ -137,7 +137,8 @@ <h3 id="cargo_rustc_feature_selection">Feature Selection</h3>
 <dd>
 <p>Space or comma separated list of features to activate. These features only
 apply to the current directory&#8217;s package. Features of direct dependencies
-may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
+may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax. This flag may be
+specified multiple times, which enables all specified features.</p>
 </dd>
 <dt class="hdlist1"><strong>--all-features</strong></dt>
 <dd>
@@ -165,6 +166,11 @@ <h3 id="cargo_rustc_compilation_options">Compilation Options</h3>
 <p>This may also be specified with the <code>build.target</code>
 <a href="../reference/config.html">config value</a>.</p>
 </div>
+<div class="paragraph">
+<p>Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
+</div>
 </dd>
 <dt class="hdlist1"><strong>--release</strong></dt>
 <dd>