Add warning if potentially-scrapable examples are skipped due to dev-dependencies

Author: willcrichton

src/cargo/ops/cargo_compile/unit_generator.rs

@@ -1,3 +1,4 @@
+use std::cell::RefCell;
 use std::collections::{HashMap, HashSet};
 use std::fmt::Write;
 
@@ -458,6 +459,7 @@ impl<'a> UnitGenerator<'a, '_> {
             .map(|u| &u.pkg)
             .collect::<HashSet<_>>();
 
+        let skipped_examples: RefCell<Vec<Target>> = RefCell::new(Vec::new());
         let can_scrape = |target: &Target| {
             match (target.doc_scrape_examples(), target.is_example()) {
                 // Targets configured by the user to not be scraped should never be scraped
@@ -466,7 +468,12 @@ impl<'a> UnitGenerator<'a, '_> {
                 (RustdocScrapeExamples::Enabled, _) => true,
                 // Example targets with no configuration should be conditionally scraped if
                 // it's guaranteed not to break the build
-                (RustdocScrapeExamples::Unset, true) => safe_to_scrape_example_targets,
+                (RustdocScrapeExamples::Unset, true) => {
+                    if !safe_to_scrape_example_targets {
+                        skipped_examples.borrow_mut().push(target.clone());
+                    }
+                    safe_to_scrape_example_targets
+                }
                 // All other targets are ignored for now. This may change in the future!
                 (RustdocScrapeExamples::Unset, false) => false,
             }
@@ -475,6 +482,22 @@ impl<'a> UnitGenerator<'a, '_> {
         let mut scrape_proposals = self.filter_targets(can_scrape, false, CompileMode::Docscrape);
         scrape_proposals.retain(|proposal| pkgs_to_scrape.contains(proposal.pkg));
 
+        let skipped_examples = skipped_examples.into_inner();
+        if !skipped_examples.is_empty() {
+            let mut shell = self.ws.config().shell();
+            let example_str = skipped_examples
+                .into_iter()
+                .map(|t| t.description_named())
+                .collect::<Vec<_>>()
+                .join(", ");
+            shell.warn(format!(
+                "\
+Rustdoc did not scrape the following examples because they require dev-dependencies: {example_str}
+    If you want Rustdoc to scrape these examples, then add `doc-scrape-examples = true`
+    to the [[example]] target configuration of at least one example."
+            ))?;
+        }
+
         Ok(scrape_proposals)
     }
 

tests/testsuite/docscrape.rs

@@ -429,7 +429,7 @@ error: expected one of `!` or `::`, found `NOT`
 fn no_scrape_with_dev_deps() {
     // Tests that a crate with dev-dependencies does not have its examples
     // scraped unless explicitly prompted to check them. See
-    // `CompileFilter::refine_for_docscrape` for details on why.
+    // `UnitGenerator::create_docscrape_proposals` for details on why.
 
     let p = project()
         .file(
@@ -440,9 +440,6 @@ fn no_scrape_with_dev_deps() {
             version = "0.0.1"
             authors = []
 
-            [lib]
-            doc-scrape-examples = false
-
             [dev-dependencies]
             a = {path = "a"}
         "#,
@@ -461,17 +458,21 @@ fn no_scrape_with_dev_deps() {
         .file("a/src/lib.rs", "pub fn f() {}")
         .build();
 
-    // If --examples is not provided, then the example is never scanned.
+    // If --examples is not provided, then the example is not scanned, and a warning
+    // should be raised.
     p.cargo("doc -Zunstable-options -Z rustdoc-scrape-examples")
         .masquerade_as_nightly_cargo(&["rustdoc-scrape-examples"])
         .with_stderr(
             "\
+warning: Rustdoc did not scrape the following examples because they require dev-dependencies: example \"ex\"
+    If you want Rustdoc to scrape these examples, then add `doc-scrape-examples = true`
+    to the [[example]] target configuration of at least one example.
 [DOCUMENTING] foo v0.0.1 ([CWD])
 [FINISHED] dev [unoptimized + debuginfo] target(s) in [..]",
         )
         .run();
 
-    // If --examples is provided, then the bad example is scanned and ignored.
+    // If --examples is provided, then the example is scanned.
     p.cargo("doc --examples -Zunstable-options -Z rustdoc-scrape-examples")
         .masquerade_as_nightly_cargo(&["rustdoc-scrape-examples"])
         .with_stderr_unordered(
@@ -497,9 +498,6 @@ fn use_dev_deps_if_explicitly_enabled() {
             version = "0.0.1"
             authors = []
 
-            [lib]
-            doc-scrape-examples = false
-
             [[example]]
             name = "ex"
             doc-scrape-examples = true