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

Author: bors

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>