Update docs

rust-lang · Dec 5, 2021 · 8c7c35e · 8c7c35e
1 parent c2332dc
commit 8c7c35e
Show file tree

Hide file tree

Showing 26 changed files with 281 additions and 30 deletions.
diff --git a/src/doc/man/cargo-build.md b/src/doc/man/cargo-build.md
@@ -89,6 +89,7 @@ See <https://github.com/rust-lang/cargo/issues/5579> for more information.
 
 {{#options}}
 {{> options-jobs }}
+{{> options-future-incompat }}
 {{/options}}
 
 {{> section-environment }}

diff --git a/src/doc/man/cargo-check.md b/src/doc/man/cargo-check.md
@@ -74,6 +74,7 @@ they have `required-features` that are missing.
 
 {{#options}}
 {{> options-jobs }}
+{{> options-future-incompat }}
 {{/options}}
 
 {{> section-environment }}

diff --git a/src/doc/man/cargo-report.md b/src/doc/man/cargo-report.md
@@ -0,0 +1,40 @@
+# cargo-report(1)
+
+## NAME
+
+cargo-report - Generate and display various kinds of reports
+
+## SYNOPSIS
+
+`cargo report` _type_ [_options_]
+
+### DESCRIPTION
+
+Displays a report of the given _type_ - currently, only `future-incompat` is supported
+
+## OPTIONS
+
+{{#options}}
+
+{{#option "`--id` _id_" }}
+Show the report with the specified Cargo-generated id
+{{/option}}
+
+{{#option "`-p` _spec_..." "`--package` _spec_..." }}
+Only display a report for the specified package
+{{/option}}
+
+{{/options}}
+
+## EXAMPLES
+
+1. Display the latest future-incompat report:
+
+       cargo report future-incompat
+
+2. Display the latest future-incompat report for a specific package:
+
+       cargo report future-incompat --package my-dep:0.0.1
+
+## SEE ALSO
+{{man "cargo" 1}}
diff --git a/src/doc/man/cargo-rustc.md b/src/doc/man/cargo-rustc.md
@@ -100,6 +100,7 @@ See the [the reference](../reference/profiles.html) for more details on profiles
 
 {{#options}}
 {{> options-jobs }}
+{{> options-future-incompat }}
 {{/options}}
 
 {{> section-environment }}

diff --git a/src/doc/man/cargo-test.md b/src/doc/man/cargo-test.md
@@ -153,6 +153,7 @@ includes an option to control the number of threads used:
 {{#options}}
 
 {{> options-jobs }}
+{{> options-future-incompat }}
 
 {{/options}}
 

diff --git a/src/doc/man/generated_txt/cargo-build.txt b/src/doc/man/generated_txt/cargo-build.txt
@@ -287,6 +287,12 @@ OPTIONS
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
            the number of CPUs.
 
+       --future-incompat-report
+           Displays a future-incompat report for any future-incompatible
+           warnings produced during execution of this command
+
+           See cargo-report(1)
+
 ENVIRONMENT
        See the reference
        <https://doc.rust-lang.org/cargo/reference/environment-variables.html>

diff --git a/src/doc/man/generated_txt/cargo-check.txt b/src/doc/man/generated_txt/cargo-check.txt
@@ -281,6 +281,12 @@ OPTIONS
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
            the number of CPUs.
 
+       --future-incompat-report
+           Displays a future-incompat report for any future-incompatible
+           warnings produced during execution of this command
+
+           See cargo-report(1)
+
 ENVIRONMENT
        See the reference
        <https://doc.rust-lang.org/cargo/reference/environment-variables.html>

diff --git a/src/doc/man/generated_txt/cargo-report.txt b/src/doc/man/generated_txt/cargo-report.txt
@@ -0,0 +1,31 @@
+CARGO-REPORT(1)
+
+NAME
+       cargo-report - Generate and display various kinds of reports
+
+SYNOPSIS
+       cargo report type [options]
+
+   DESCRIPTION
+       Displays a report of the given type - currently, only future-incompat is
+       supported
+
+OPTIONS
+       --id id
+           Show the report with the specified Cargo-generated id
+
+       -p spec..., --package spec...
+           Only display a report for the specified package
+
+EXAMPLES
+       1. Display the latest future-incompat report:
+
+              cargo report future-incompat
+
+       2. Display the latest future-incompat report for a specific package:
+
+              cargo report future-incompat --package my-dep:0.0.1
+
+SEE ALSO
+       cargo(1)
+
diff --git a/src/doc/man/generated_txt/cargo-rustc.txt b/src/doc/man/generated_txt/cargo-rustc.txt
@@ -276,6 +276,12 @@ OPTIONS
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
            the number of CPUs.
 
+       --future-incompat-report
+           Displays a future-incompat report for any future-incompatible
+           warnings produced during execution of this command
+
+           See cargo-report(1)
+
 ENVIRONMENT
        See the reference
        <https://doc.rust-lang.org/cargo/reference/environment-variables.html>

diff --git a/src/doc/man/generated_txt/cargo-test.txt b/src/doc/man/generated_txt/cargo-test.txt
@@ -357,6 +357,12 @@ OPTIONS
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
            the number of CPUs.
 
+       --future-incompat-report
+           Displays a future-incompat report for any future-incompatible
+           warnings produced during execution of this command
+
+           See cargo-report(1)
+
 ENVIRONMENT
        See the reference
        <https://doc.rust-lang.org/cargo/reference/environment-variables.html>

diff --git a/src/doc/man/includes/options-future-incompat.md b/src/doc/man/includes/options-future-incompat.md
@@ -0,0 +1,6 @@
+{{#option "`--future-incompat-report`"}}
+Displays a future-incompat report for any future-incompatible warnings
+produced during execution of this command
+
+See {{man "cargo-report" 1}}
+{{/option}}
diff --git a/src/doc/src/SUMMARY.md b/src/doc/src/SUMMARY.md
@@ -38,6 +38,7 @@
     * [Registries](reference/registries.md)
     * [Dependency Resolution](reference/resolver.md)
     * [SemVer Compatibility](reference/semver.md)
+    * [Future incompat report](reference/future-incompat-report.md)
     * [Unstable Features](reference/unstable.md)
 
 * [Cargo Commands](commands/index.md)
@@ -57,6 +58,7 @@
         * [cargo rustc](commands/cargo-rustc.md)
         * [cargo rustdoc](commands/cargo-rustdoc.md)
         * [cargo test](commands/cargo-test.md)
+        * [cargo report](commands/cargo-report.md)
     * [Manifest Commands](commands/manifest-commands.md)
         * [cargo generate-lockfile](commands/cargo-generate-lockfile.md)
         * [cargo locate-project](commands/cargo-locate-project.md)

diff --git a/src/doc/src/commands/build-commands.md b/src/doc/src/commands/build-commands.md
@@ -10,3 +10,4 @@
 * [cargo rustc](cargo-rustc.md)
 * [cargo rustdoc](cargo-rustdoc.md)
 * [cargo test](cargo-test.md)
+* [cargo report](cargo-report.md)
diff --git a/src/doc/src/commands/cargo-build.md b/src/doc/src/commands/cargo-build.md
@@ -354,6 +354,12 @@ for more information about how toolchain overrides work.</dd>
 the number of CPUs.</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>
+<dd class="option-desc">Displays a future-incompat report for any future-incompatible warnings
+produced during execution of this command</p>
+<p>See <a href="cargo-report.html">cargo-report(1)</a></dd>
+
+
 </dl>
 
 ## ENVIRONMENT

diff --git a/src/doc/src/commands/cargo-check.md b/src/doc/src/commands/cargo-check.md
@@ -345,6 +345,12 @@ for more information about how toolchain overrides work.</dd>
 the number of CPUs.</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>
+<dd class="option-desc">Displays a future-incompat report for any future-incompatible warnings
+produced during execution of this command</p>
+<p>See <a href="cargo-report.html">cargo-report(1)</a></dd>
+
+
 </dl>
 
 ## ENVIRONMENT

diff --git a/src/doc/src/commands/cargo-report.md b/src/doc/src/commands/cargo-report.md
@@ -0,0 +1,41 @@
+# cargo-report(1)
+
+## NAME
+
+cargo-report - Generate and display various kinds of reports
+
+## SYNOPSIS
+
+`cargo report` _type_ [_options_]
+
+### DESCRIPTION
+
+Displays a report of the given _type_ - currently, only `future-incompat` is supported
+
+## OPTIONS
+
+<dl>
+
+<dt class="option-term" id="option-cargo-report---id"><a class="option-anchor" href="#option-cargo-report---id"></a><code>--id</code> <em>id</em></dt>
+<dd class="option-desc">Show the report with the specified Cargo-generated id</dd>
+
+
+<dt class="option-term" id="option-cargo-report--p"><a class="option-anchor" href="#option-cargo-report--p"></a><code>-p</code> <em>spec</em>...</dt>
+<dt class="option-term" id="option-cargo-report---package"><a class="option-anchor" href="#option-cargo-report---package"></a><code>--package</code> <em>spec</em>...</dt>
+<dd class="option-desc">Only display a report for the specified package</dd>
+
+
+</dl>
+
+## EXAMPLES
+
+1. Display the latest future-incompat report:
+
+       cargo report future-incompat
+
+2. Display the latest future-incompat report for a specific package:
+
+       cargo report future-incompat --package my-dep:0.0.1
+
+## SEE ALSO
+[cargo(1)](cargo.html)
diff --git a/src/doc/src/commands/cargo-rustc.md b/src/doc/src/commands/cargo-rustc.md
@@ -337,6 +337,12 @@ for more information about how toolchain overrides work.</dd>
 the number of CPUs.</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>
+<dd class="option-desc">Displays a future-incompat report for any future-incompatible warnings
+produced during execution of this command</p>
+<p>See <a href="cargo-report.html">cargo-report(1)</a></dd>
+
+
 </dl>
 
 ## ENVIRONMENT

diff --git a/src/doc/src/commands/cargo-test.md b/src/doc/src/commands/cargo-test.md
@@ -434,6 +434,12 @@ includes an option to control the number of threads used:
 the number of CPUs.</dd>
 
 
+<dt class="option-term" id="option-cargo-test---future-incompat-report"><a class="option-anchor" href="#option-cargo-test---future-incompat-report"></a><code>--future-incompat-report</code></dt>
+<dd class="option-desc">Displays a future-incompat report for any future-incompatible warnings
+produced during execution of this command</p>
+<p>See <a href="cargo-report.html">cargo-report(1)</a></dd>
+
+
 
 </dl>
 

diff --git a/src/doc/src/reference/future-incompat-report.md b/src/doc/src/reference/future-incompat-report.md
@@ -0,0 +1,24 @@
+### Future incompat report
+
+Cargo checks for  future-incompatible warnings in all dependencies. These are warnings for
+changes that may become hard errors in the future, causing the dependency to
+stop building in a future version of rustc. If any warnings are found, a small
+notice is displayed indicating that the warnings were found, and provides
+instructions on how to display a full report.
+
+A full report can be displayed with the `cargo report future-incompatibilities
+--id ID` command, or by running the build again with
+the `--future-incompat-report` flag. The developer should then update their
+dependencies to a version where the issue is fixed, or work with the
+developers of the dependencies to help resolve the issue.
+
+This feature can be configured through a `[future-incompat-report]`
+section in `.cargo/config`. Currently, the supported options are:
+
+```
+[future-incompat-report]
+frequency = FREQUENCY
+```
+
+The supported values for `FREQUENCY` are 'always` and 'never', which control
+whether or not a message is printed out at the end of `cargo build` / `cargo check`.
diff --git a/src/doc/src/reference/index.md b/src/doc/src/reference/index.md
@@ -21,4 +21,5 @@ The reference covers the details of various areas of Cargo.
 * [Registries](registries.md)
 * [Dependency Resolution](resolver.md)
 * [SemVer Compatibility](semver.md)
+* [Future incompat report](future-incompat-report.md)
 * [Unstable Features](unstable.md)
diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md
@@ -94,7 +94,6 @@ Each new feature described below should explain how to use it.
     * [Build-plan](#build-plan) — Emits JSON information on which commands will be run.
     * [timings](#timings) — Generates a report on how long individual dependencies took to run.
     * [unit-graph](#unit-graph) — Emits JSON for Cargo's internal graph structure.
-    * [future incompat report](#future-incompat-report) — Displays a report for future incompatibilities that may error in the future.
     * [`cargo rustc --print`](#rustc---print) — Calls rustc with `--print` to display information from rustc.
 * Configuration
     * [config-cli](#config-cli) — Adds the ability to pass configuration options on the command-line.
@@ -1143,35 +1142,6 @@ cargo logout -Z credential-process
 [crates.io]: https://crates.io/
 [config file]: config.md
 
-### future incompat report
-* RFC: [#2834](https://github.com/rust-lang/rfcs/blob/master/text/2834-cargo-report-future-incompat.md)
-* rustc Tracking Issue: [#71249](https://github.com/rust-lang/rust/issues/71249)
-
-The `-Z future-incompat-report` flag causes Cargo to check for
-future-incompatible warnings in all dependencies. These are warnings for
-changes that may become hard errors in the future, causing the dependency to
-stop building in a future version of rustc. If any warnings are found, a small
-notice is displayed indicating that the warnings were found, and provides
-instructions on how to display a full report.
-
-A full report can be displayed with the `cargo report future-incompatibilities
--Z future-incompat-report --id ID` command, or by running the build again with
-the `--future-incompat-report` flag. The developer should then update their
-dependencies to a version where the issue is fixed, or work with the
-developers of the dependencies to help resolve the issue.
-
-This feature can be configured through a `[future-incompat-report]`
-section in `.cargo/config`. Currently, the supported options are:
-
-```
-[future-incompat-report]
-frequency = FREQUENCY
-```
-
-The supported values for `FREQUENCY` are 'always` and 'never', which control
-whether or not a message is printed out at the end of `cargo build` / `cargo check`.
-
-
 ### `cargo config`
 
 * Original Issue: [#2362](https://github.com/rust-lang/cargo/issues/2362)
@@ -1403,6 +1373,11 @@ See [`cargo fix --edition`](../commands/cargo-fix.md) and [The Edition Guide](..
 Custom named profiles have been stabilized in the 1.57 release. See the
 [profiles chapter](profiles.md#custom-profiles) for more information.
 
+### Future incompat report
+
+Support for generating a future-incompat report has been stabilized
+in the 1.59 release. See the [future incompat report chapter](future-incompat-report.md)
+for more information.
 
 ### scrape-examples
 

diff --git a/src/etc/man/cargo-build.1 b/src/etc/man/cargo-build.1
@@ -359,6 +359,14 @@ Number of parallel jobs to run. May also be specified with the
 \fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
 the number of CPUs.
 .RE
+.sp
+\fB\-\-future\-incompat\-report\fR
+.RS 4
+Displays a future\-incompat report for any future\-incompatible warnings
+produced during execution of this command
+.sp
+See \fBcargo\-report\fR(1)
+.RE
 .SH "ENVIRONMENT"
 See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
 details on environment variables that Cargo reads.

diff --git a/src/etc/man/cargo-check.1 b/src/etc/man/cargo-check.1
@@ -349,6 +349,14 @@ Number of parallel jobs to run. May also be specified with the
 \fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
 the number of CPUs.
 .RE
+.sp
+\fB\-\-future\-incompat\-report\fR
+.RS 4
+Displays a future\-incompat report for any future\-incompatible warnings
+produced during execution of this command
+.sp
+See \fBcargo\-report\fR(1)
+.RE
 .SH "ENVIRONMENT"
 See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
 details on environment variables that Cargo reads.