Add documentation and a test

Author: willcrichton

src/cargo/core/compiler/build_config.rs

@@ -138,21 +138,18 @@ pub enum CompileMode {
     /// Building a target with `rustc` to emit `rmeta` metadata only. If
     /// `test` is true, then it is also compiled with `--test` to check it like
     /// a test.
-    Check {
-        test: bool,
-    },
+    Check { test: bool },
     /// Used to indicate benchmarks should be built. This is not used in
     /// `Unit`, because it is essentially the same as `Test` (indicating
     /// `--test` should be passed to rustc) and by using `Test` instead it
     /// allows some de-duping of Units to occur.
     Bench,
     /// A target that will be documented with `rustdoc`.
     /// If `deps` is true, then it will also document all dependencies.
-    Doc {
-        deps: bool,
-    },
+    Doc { deps: bool },
     /// A target that will be tested with `rustdoc`.
     Doctest,
+    /// An example or library that will be scraped for function calls by `rustdoc`.
     Docscrape,
     /// A marker for Units that represent the execution of a `build.rs` script.
     RunCustomBuild,

src/cargo/core/compiler/build_context/mod.rs

@@ -47,6 +47,7 @@ pub struct BuildContext<'a, 'cfg> {
     /// The dependency graph of units to compile.
     pub unit_graph: UnitGraph,
 
+    /// Reverse-dependencies of documented units, used by the rustdoc --scrape-examples flag.
     pub scrape_units: Vec<Unit>,
 
     /// The list of all kinds that are involved in this build

src/cargo/core/compiler/mod.rs

@@ -648,6 +648,30 @@ fn rustdoc(cx: &mut Context<'_, '_>, unit: &Unit) -> CargoResult<Work> {
         rustdoc.args(args);
     }
 
+    // rustdoc needs a -Cmetadata flag in order to recognize StableCrateIds that refer to
+    // items in the crate being documented. The -Cmetadata flag used by reverse-dependencies
+    // will be the metadata of the Cargo unit that generated the current library's rmeta file,
+    // which should be a Check unit.
+    //
+    // If the current crate has reverse-dependencies, such a Check unit should exist, and so
+    // we use that crate's metadata. If not, we use the crate's Doc unit so at least examples
+    // scraped from the current crate can be used when documenting the current crate.
+    let matching_units = cx
+        .bcx
+        .unit_graph
+        .keys()
+        .filter(|other| {
+            unit.pkg == other.pkg && unit.target == other.target && !other.mode.is_doc_scrape()
+        })
+        .collect::<Vec<_>>();
+    let metadata_unit = matching_units
+        .iter()
+        .find(|other| other.mode.is_check())
+        .or_else(|| matching_units.iter().find(|other| other.mode.is_doc()))
+        .unwrap_or(&unit);
+    let metadata = cx.files().metadata(metadata_unit);
+    rustdoc.arg("-C").arg(format!("metadata={}", metadata));
+
     let scrape_output_path = |unit: &Unit| -> CargoResult<PathBuf> {
         let layout = cx.files().layout(unit.kind);
         let output_dir = layout.prepare_tmp()?;
@@ -661,6 +685,7 @@ fn rustdoc(cx: &mut Context<'_, '_>, unit: &Unit) -> CargoResult<Work> {
             .arg("--scrape-examples-output-path")
             .arg(scrape_output_path(unit)?);
 
+        // Limit the scraped examples to just crates in the root set
         let root_packages = cx
             .bcx
             .roots
@@ -671,26 +696,12 @@ fn rustdoc(cx: &mut Context<'_, '_>, unit: &Unit) -> CargoResult<Work> {
             rustdoc.arg("--scrape-examples-target-crate").arg(pkg);
         }
     } else if cx.bcx.scrape_units.len() > 0 && cx.bcx.roots.contains(unit) {
-        let all_units = cx
-            .bcx
-            .unit_graph
-            .values()
-            .map(|deps| deps.iter().map(|dep| &dep.unit))
-            .flatten();
-        let check_unit = all_units.into_iter().find(|other| {
-            unit.pkg == other.pkg && unit.target == other.target && other.mode.is_check()
-        });
-        if let Some(check_unit) = check_unit {
-            let metadata = cx.files().metadata(check_unit);
-            rustdoc.arg("-C").arg(format!("metadata={}", metadata));
-
-            rustdoc.arg("-Zunstable-options");
+        rustdoc.arg("-Zunstable-options");
 
-            for scrape_unit in &cx.bcx.scrape_units {
-                rustdoc
-                    .arg("--with-examples")
-                    .arg(scrape_output_path(scrape_unit)?);
-            }
+        for scrape_unit in &cx.bcx.scrape_units {
+            rustdoc
+                .arg("--with-examples")
+                .arg(scrape_output_path(scrape_unit)?);
         }
     }
 

src/cargo/core/compiler/unit_dependencies.rs

@@ -47,7 +47,7 @@ struct State<'a, 'cfg> {
     target_data: &'a RustcTargetData<'cfg>,
     profiles: &'a Profiles,
     interner: &'a UnitInterner,
-    scrape_roots: &'a [Unit],
+    scrape_units: &'a [Unit],
 
     /// A set of edges in `unit_dependencies` where (a, b) means that the
     /// dependency from a to b was added purely because it was a dev-dependency.
@@ -62,7 +62,7 @@ pub fn build_unit_dependencies<'a, 'cfg>(
     features: &'a ResolvedFeatures,
     std_resolve: Option<&'a (Resolve, ResolvedFeatures)>,
     roots: &[Unit],
-    scrape_roots: &[Unit],
+    scrape_units: &[Unit],
     std_roots: &HashMap<CompileKind, Vec<Unit>>,
     global_mode: CompileMode,
     target_data: &'a RustcTargetData<'cfg>,
@@ -93,7 +93,7 @@ pub fn build_unit_dependencies<'a, 'cfg>(
         target_data,
         profiles,
         interner,
-        scrape_roots,
+        scrape_units,
         dev_dependency_edges: HashSet::new(),
     };
 
@@ -422,8 +422,6 @@ fn compute_deps_doc(
     state: &mut State<'_, '_>,
     unit_for: UnitFor,
 ) -> CargoResult<Vec<UnitDep>> {
-    // FIXME(wcrichto): target.is_lib() is probably not the correct way to check
-    //   if the unit needs dev-dependencies
     let deps = state.deps(unit, unit_for, &|dep| dep.kind() == DepKind::Normal);
 
     // To document a library, we depend on dependencies actually being
@@ -473,7 +471,8 @@ fn compute_deps_doc(
         ret.extend(maybe_lib(unit, state, unit_for)?);
     }
 
-    for scrape_unit in state.scrape_roots.iter() {
+    // Add all units being scraped for examples as a dependency of Doc units.
+    for scrape_unit in state.scrape_units.iter() {
         let unit_for = UnitFor::new_normal();
         deps_of(scrape_unit, state, unit_for)?;
         ret.push(new_unit_dep(
@@ -715,6 +714,8 @@ fn connect_run_custom_build_deps(state: &mut State<'_, '_>) {
                         && other.unit.target.is_linkable()
                         && other.unit.pkg.manifest().links().is_some()
                 })
+                // Avoid cycles when using the --scrape-examples feature
+                // FIXME(wcrichto): unclear why this exact filter is the fix
                 .filter(|(_, other)| !other.unit.mode.is_doc_scrape())
                 // Skip dependencies induced via dev-dependencies since
                 // connections between `links` and build scripts only happens

tests/testsuite/doc.rs

@@ -2148,3 +2148,40 @@ fn doc_fingerprint_unusual_behavior() {
     assert!(build_doc.join("somefile").exists());
     assert!(real_doc.join("somefile").exists());
 }
+
+#[cargo_test]
+fn scrape_examples() {
+    if !is_nightly() {
+        // --scrape-examples is unstable
+        return;
+    }
+
+    let p = project()
+        .file(
+            "Cargo.toml",
+            r#"
+                [package]
+                name = "foo"
+                version = "0.0.1"
+                authors = []
+            "#,
+        )
+        .file("examples/ex.rs", "fn main() { foo::foo(); }")
+        .file("src/lib.rs", "pub fn foo() {}\npub fn bar() { foo(); }")
+        .build();
+
+    p.cargo("doc -Zunstable-options --scrape-examples all")
+        .masquerade_as_nightly_cargo()
+        .with_stderr(
+            "\
+[..] foo v0.0.1 ([CWD])
+[..] foo v0.0.1 ([CWD])
+[FINISHED] dev [unoptimized + debuginfo] target(s) in [..]
+",
+        )
+        .run();
+
+    let doc_html = p.read_file("target/doc/foo/fn.foo.html");
+    assert!(doc_html.contains("Examples found in repository"));
+    assert!(doc_html.contains("More examples"));
+}