Auto merge of #9092 - ehuss:unstable-updates, r=alexcrichton

Unstable updates

This is a collection of updates for unstable/nightly feature support, intended to provide better messages for users and better internal and external documentation.  Separated by commit, in summary:

* Added comments and new docstrings for improved internal documentation.
* Added new documentation to the reference guide on how unstable things work.
  * Also added redirects for stabilized features so any external links won't be broken.
* Add a targeted error message if you put `cargo-features` in the wrong place in `Cargo.toml`.
* Remove `publish-lockfile`.  The feature was stabilized without the key in #7026 about 1.5 years ago.  Also added "removed" support for features, which prints out a more helpful error message.
* Add help messages about stabilized `-Z` flags (instead of spitting out an unhelpful error message).
* Add help messages about stabilized `cargo-features` features.
* Add more context to the error when using `cargo-features` on stable.
* Unhide nightly CLI flags. I changed my mind on how these should work. I think it is useful to "advertise" the existence of these options on stable. The error message if you try to use it should help guide on what to do.

Closes #9074.

src/bin/cargo/cli.rs

@@ -327,9 +327,12 @@ See 'cargo help <command>' for more information on a specific command.\n",
         .arg(opt("locked", "Require Cargo.lock is up to date").global(true))
         .arg(opt("offline", "Run without accessing the network").global(true))
         .arg(
-            multi_opt("config", "KEY=VALUE", "Override a configuration value")
-                .global(true)
-                .hidden(true),
+            multi_opt(
+                "config",
+                "KEY=VALUE",
+                "Override a configuration value (unstable)",
+            )
+            .global(true),
         )
         .arg(
             Arg::with_name("unstable-features")

src/bin/cargo/commands/login.rs

@@ -10,6 +10,7 @@ pub fn cli() -> App {
         )
         .arg(opt("quiet", "No output printed to stdout").short("q"))
         .arg(Arg::with_name("token"))
+        // --host is deprecated (use --registry instead)
         .arg(
             opt("host", "Host to set the token for")
                 .value_name("HOST")

src/bin/cargo/commands/tree.rs

@@ -19,7 +19,9 @@ pub fn cli() -> App {
             "Display the tree for all packages in the workspace",
             "Exclude specific workspace members",
         )
+        // Deprecated, use --no-dedupe instead.
         .arg(Arg::with_name("all").long("all").short("a").hidden(true))
+        // Deprecated, use --target=all instead.
         .arg(
             Arg::with_name("all-targets")
                 .long("all-targets")
@@ -30,6 +32,7 @@ pub fn cli() -> App {
             "Filter dependencies matching the given target-triple (default host platform). \
             Pass `all` to include all targets.",
         )
+        // Deprecated, use -e=no-dev instead.
         .arg(
             Arg::with_name("no-dev-dependencies")
                 .long("no-dev-dependencies")
@@ -52,7 +55,9 @@ pub fn cli() -> App {
             )
             .short("i"),
         )
+        // Deprecated, use --prefix=none instead.
         .arg(Arg::with_name("no-indent").long("no-indent").hidden(true))
+        // Deprecated, use --prefix=depth instead.
         .arg(
             Arg::with_name("prefix-depth")
                 .long("prefix-depth")

src/bin/cargo/commands/vendor.rs

@@ -32,21 +32,25 @@ pub fn cli() -> App {
                 .long("versioned-dirs")
                 .help("Always include version in subdir name"),
         )
+        // Not supported.
         .arg(
             Arg::with_name("no-merge-sources")
                 .long("no-merge-sources")
                 .hidden(true),
         )
+        // Not supported.
         .arg(
             Arg::with_name("relative-path")
                 .long("relative-path")
                 .hidden(true),
         )
+        // Not supported.
         .arg(
             Arg::with_name("only-git-deps")
                 .long("only-git-deps")
                 .hidden(true),
         )
+        // Not supported.
         .arg(
             Arg::with_name("disallow-duplicates")
                 .long("disallow-duplicates")