From 1ea41babdc1c1a81761c4b894082d753e3b0fe2d Mon Sep 17 00:00:00 2001
From: Alex Tokarev <aleksator@gmail.com>
Date: Wed, 19 Feb 2020 02:11:16 +0300
Subject: [PATCH 1/2] Add an option to include crate versions to the generated
 docs

Fixes https://github.com/rust-lang/cargo/issues/1681
---
 src/bin/cargo/cli.rs           |  1 +
 src/cargo/core/compiler/mod.rs | 16 ++++++++++++++++
 src/cargo/core/features.rs     |  2 ++
 tests/testsuite/doc.rs         | 33 +++++++++++++++++++++++++++++++++
 4 files changed, 52 insertions(+)

diff --git a/src/bin/cargo/cli.rs b/src/bin/cargo/cli.rs
index 567a5ece735..25d89c01af9 100644
--- a/src/bin/cargo/cli.rs
+++ b/src/bin/cargo/cli.rs
@@ -38,6 +38,7 @@ Available unstable (nightly-only) flags:
     -Z unstable-options -- Allow the usage of unstable options
     -Z timings          -- Display concurrency information
     -Z doctest-xcompile -- Compile and run doctests for non-host target using runner config
+    -Z crate-versions   -- Add crate versions to generated docs
 
 Run with 'cargo -Z [FLAG] [SUBCOMMAND]'"
         );
diff --git a/src/cargo/core/compiler/mod.rs b/src/cargo/core/compiler/mod.rs
index 8dce6ff31ae..8c678aa0c7e 100644
--- a/src/cargo/core/compiler/mod.rs
+++ b/src/cargo/core/compiler/mod.rs
@@ -558,6 +558,7 @@ fn rustdoc<'a, 'cfg>(cx: &mut Context<'a, 'cfg>, unit: &Unit<'a>) -> CargoResult
     let mut rustdoc = cx.compilation.rustdoc_process(unit.pkg, unit.target)?;
     rustdoc.inherit_jobserver(&cx.jobserver);
     rustdoc.arg("--crate-name").arg(&unit.target.crate_name());
+    add_crate_versions_if_requested(bcx, unit, &mut rustdoc);
     add_path_args(bcx, unit, &mut rustdoc);
     add_cap_lints(bcx, unit, &mut rustdoc);
 
@@ -624,6 +625,21 @@ fn rustdoc<'a, 'cfg>(cx: &mut Context<'a, 'cfg>, unit: &Unit<'a>) -> CargoResult
     }))
 }
 
+fn add_crate_versions_if_requested(
+    bcx: &BuildContext<'_, '_>,
+    unit: &Unit<'_>,
+    rustdoc: &mut ProcessBuilder,
+) {
+    if !bcx.config.cli_unstable().crate_versions {
+        return;
+    }
+    rustdoc
+        .arg("-Z")
+        .arg("unstable-options")
+        .arg("--crate-version")
+        .arg(&unit.pkg.version().to_string());
+}
+
 // The path that we pass to rustc is actually fairly important because it will
 // show up in error messages (important for readability), debug information
 // (important for caching), etc. As a result we need to be pretty careful how we
diff --git a/src/cargo/core/features.rs b/src/cargo/core/features.rs
index f08aa0d33f8..634855176d7 100644
--- a/src/cargo/core/features.rs
+++ b/src/cargo/core/features.rs
@@ -342,6 +342,7 @@ pub struct CliUnstable {
     pub panic_abort_tests: bool,
     pub jobserver_per_rustc: bool,
     pub features: Option<Vec<String>>,
+    pub crate_versions: bool,
 }
 
 impl CliUnstable {
@@ -418,6 +419,7 @@ impl CliUnstable {
             "panic-abort-tests" => self.panic_abort_tests = parse_empty(k, v)?,
             "jobserver-per-rustc" => self.jobserver_per_rustc = parse_empty(k, v)?,
             "features" => self.features = Some(parse_features(v)),
+            "crate-versions" => self.crate_versions = parse_empty(k, v)?,
             _ => bail!("unknown `-Z` flag specified: {}", k),
         }
 
diff --git a/tests/testsuite/doc.rs b/tests/testsuite/doc.rs
index c8e943aca0d..8bf3fdd84ab 100644
--- a/tests/testsuite/doc.rs
+++ b/tests/testsuite/doc.rs
@@ -1510,3 +1510,36 @@ fn bin_private_items_deps() {
     assert!(p.root().join("target/doc/bar/fn.bar_pub.html").is_file());
     assert!(!p.root().join("target/doc/bar/fn.bar_priv.html").exists());
 }
+
+#[cargo_test]
+fn crate_versions() {
+    // Testing unstable flag
+    if !is_nightly() {
+        return;
+    }
+    let p = project()
+        .file(
+            "Cargo.toml",
+            r#"
+            [package]
+            name = "foo"
+            version = "1.2.4"
+            authors = []
+        "#,
+        )
+        .file("src/lib.rs", "")
+        .build();
+
+    p.cargo("-Z crate-versions doc")
+        .masquerade_as_nightly_cargo()
+        .run();
+
+    let doc_file = p.root().join("target/doc/foo/index.html");
+    let mut doc_html = String::new();
+    File::open(&doc_file)
+        .unwrap()
+        .read_to_string(&mut doc_html)
+        .unwrap();
+
+    assert!(doc_html.contains("Version 1.2.4"));
+}

From fc5e17ab5dee294346355a6b3a1546f0ceff9e5c Mon Sep 17 00:00:00 2001
From: Alex Tokarev <aleksator@gmail.com>
Date: Thu, 20 Feb 2020 20:17:10 +0300
Subject: [PATCH 2/2] Document unstable 'crate-versions' flag

https://github.com/rust-lang/cargo/issues/7907
---
 src/doc/src/reference/unstable.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md
index 48b32afedc1..144af8c669a 100644
--- a/src/doc/src/reference/unstable.md
+++ b/src/doc/src/reference/unstable.md
@@ -541,3 +541,10 @@ The available options are:
 
 * `compare` — This option compares the resolved features to the old resolver,
   and will print any differences.
+
+### crate-versions
+* Tracking Issue: [#7907](https://github.com/rust-lang/cargo/issues/7907)
+
+The `-Z crate-versions` flag will make `cargo doc` include appropriate crate versions for the current crate and all of its dependencies (unless `--no-deps` was provided) in the compiled documentation.
+
+You can find an example screenshot for the cargo itself in the tracking issue.