Add comments and todos

Author: willcrichton

src/bin/cargo/commands/doc.rs

@@ -55,6 +55,9 @@ pub fn exec(config: &mut Config, args: &ArgMatches<'_>) -> CliResult {
     let mut compile_opts =
         args.compile_options(config, mode, Some(&ws), ProfileChecking::Custom)?;
     compile_opts.rustdoc_document_private_items = args.is_present("document-private-items");
+
+    // TODO(wcrichto): move scrape example configuration into Cargo.toml before stabilization
+    // See: https://github.com/rust-lang/cargo/pull/9525#discussion_r728470927
     compile_opts.rustdoc_scrape_examples = match args.value_of("scrape-examples") {
         Some(s) => Some(match s {
             "all" => CompileFilter::new_all_targets(),

src/cargo/core/compiler/context/compilation_files.rs

@@ -418,7 +418,8 @@ impl<'a, 'cfg: 'a> CompilationFiles<'a, 'cfg> {
                 vec![]
             }
             CompileMode::Docscrape => {
-                // FIXME(wcrichto): should this include the *.examples files?
+                // Docscrape only generates temporary *.examples files to pass to rustdoc
+                // so they're not important to track
                 vec![]
             }
             CompileMode::Test

src/cargo/core/compiler/mod.rs

@@ -696,6 +696,9 @@ 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) {
+        // We only pass scraped examples to packages in the workspace (bcx.roots)
+        // since examples are only coming from reverse-dependencies of workspace packages
+
         rustdoc.arg("-Zunstable-options");
 
         for scrape_unit in &cx.bcx.scrape_units {

src/cargo/ops/cargo_compile.rs

@@ -780,22 +780,20 @@ impl CompileFilter {
 
     pub fn need_dev_deps(&self, mode: CompileMode) -> bool {
         match mode {
-            CompileMode::Test
-            | CompileMode::Doctest
-            | CompileMode::Bench
-            | CompileMode::Docscrape => true,
+            CompileMode::Test | CompileMode::Doctest | CompileMode::Bench => true,
             CompileMode::Check { test: true } => true,
-            CompileMode::Build | CompileMode::Doc { .. } | CompileMode::Check { test: false } => {
-                match *self {
-                    CompileFilter::Default { .. } => false,
-                    CompileFilter::Only {
-                        ref examples,
-                        ref tests,
-                        ref benches,
-                        ..
-                    } => examples.is_specific() || tests.is_specific() || benches.is_specific(),
-                }
-            }
+            CompileMode::Build
+            | CompileMode::Doc { .. }
+            | CompileMode::Docscrape
+            | CompileMode::Check { test: false } => match *self {
+                CompileFilter::Default { .. } => false,
+                CompileFilter::Only {
+                    ref examples,
+                    ref tests,
+                    ref benches,
+                    ..
+                } => examples.is_specific() || tests.is_specific() || benches.is_specific(),
+            },
             CompileMode::RunCustomBuild => panic!("Invalid mode"),
         }
     }