Auto merge of #10017 - willcrichton:example-analyzer, r=alexcrichton

Change --scrape-examples flag to -Z rustdoc-scrape-examples

I'm working on getting the scrape examples feature working on docs.rs. However, docs.rs uses `cargo rustdoc` instead of `cargo doc`, and right now the `--scrape-examples` flag is only allowed for `cargo doc`. So this PR changes it to a `-Z` flag that can be passed to either command.

Author: bors

src/bin/cargo/commands/doc.rs

@@ -1,7 +1,6 @@
 use crate::command_prelude::*;
 
-use anyhow::anyhow;
-use cargo::ops::{self, CompileFilter, DocOptions, FilterRule, LibRule};
+use cargo::ops::{self, DocOptions};
 
 pub fn cli() -> App {
     subcommand("doc")
@@ -20,13 +19,6 @@ pub fn cli() -> App {
         )
         .arg(opt("no-deps", "Don't build documentation for dependencies"))
         .arg(opt("document-private-items", "Document private items"))
-        .arg(
-            opt(
-                "scrape-examples",
-                "Scrape examples to include as function documentation",
-            )
-            .value_name("FLAGS"),
-        )
         .arg_jobs()
         .arg_targets_lib_bin_example(
             "Document only this package's library",
@@ -56,33 +48,6 @@ pub fn exec(config: &mut Config, args: &ArgMatches<'_>) -> CliResult {
         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(),
-            "examples" => CompileFilter::new(
-                LibRule::False,
-                FilterRule::none(),
-                FilterRule::none(),
-                FilterRule::All,
-                FilterRule::none(),
-            ),
-            _ => {
-                return Err(CliError::from(anyhow!(
-                    r#"--scrape-examples must take "all" or "examples" as an argument"#
-                )));
-            }
-        }),
-        None => None,
-    };
-
-    if compile_opts.rustdoc_scrape_examples.is_some() {
-        config
-            .cli_unstable()
-            .fail_if_stable_opt("--scrape-examples", 9910)?;
-    }
-
     let doc_opts = DocOptions {
         open_result: args.is_present("open"),
         compile_opts,

src/cargo/core/features.rs

@@ -654,6 +654,9 @@ unstable_cli_options!(
     timings: Option<Vec<String>>  = ("Display concurrency information"),
     unstable_options: bool = ("Allow the usage of unstable options"),
     weak_dep_features: bool = ("Allow `dep_name?/feature` feature syntax"),
+    // TODO(wcrichto): move scrape example configuration into Cargo.toml before stabilization
+    // See: https://github.com/rust-lang/cargo/pull/9525#discussion_r728470927
+    rustdoc_scrape_examples: Option<String> = ("Allow rustdoc to scrape examples from reverse-dependencies for documentation"),
     skip_rustdoc_fingerprint: bool = (HIDDEN),
 );
 
@@ -871,6 +874,7 @@ impl CliUnstable {
             "namespaced-features" => self.namespaced_features = parse_empty(k, v)?,
             "weak-dep-features" => self.weak_dep_features = parse_empty(k, v)?,
             "credential-process" => self.credential_process = parse_empty(k, v)?,
+            "rustdoc-scrape-examples" => self.rustdoc_scrape_examples = v.map(|s| s.to_string()),
             "skip-rustdoc-fingerprint" => self.skip_rustdoc_fingerprint = parse_empty(k, v)?,
             "compile-progress" => stabilized_warn(k, "1.30", STABILIZED_COMPILE_PROGRESS),
             "offline" => stabilized_err(k, "1.36", STABILIZED_OFFLINE)?,

src/cargo/ops/cargo_compile.rs

@@ -45,7 +45,7 @@ use crate::util::interning::InternedString;
 use crate::util::restricted_names::is_glob_pattern;
 use crate::util::{closest_msg, profile, CargoResult, StableHasher};
 
-use anyhow::Context as _;
+use anyhow::{bail, Context as _};
 
 /// Contains information about how a package should be compiled.
 ///
@@ -76,9 +76,6 @@ pub struct CompileOptions {
     /// Whether the `--document-private-items` flags was specified and should
     /// be forwarded to `rustdoc`.
     pub rustdoc_document_private_items: bool,
-    /// Whether the `--scrape-examples` flag was specified and build flags for
-    /// examples should be forwarded to `rustdoc`.
-    pub rustdoc_scrape_examples: Option<CompileFilter>,
     /// Whether the build process should check the minimum Rust version
     /// defined in the cargo metadata for a crate.
     pub honor_rust_version: bool,
@@ -97,7 +94,6 @@ impl<'a> CompileOptions {
             target_rustc_args: None,
             local_rustdoc_args: None,
             rustdoc_document_private_items: false,
-            rustdoc_scrape_examples: None,
             honor_rust_version: true,
         })
     }
@@ -338,7 +334,6 @@ pub fn create_bcx<'a, 'cfg>(
         ref target_rustc_args,
         ref local_rustdoc_args,
         rustdoc_document_private_items,
-        ref rustdoc_scrape_examples,
         honor_rust_version,
     } = *options;
     let config = ws.config();
@@ -369,6 +364,7 @@ pub fn create_bcx<'a, 'cfg>(
     let target_data = RustcTargetData::new(ws, &build_config.requested_kinds)?;
 
     let all_packages = &Packages::All;
+    let rustdoc_scrape_examples = &config.cli_unstable().rustdoc_scrape_examples;
     let need_reverse_dependencies = rustdoc_scrape_examples.is_some();
     let full_specs = if need_reverse_dependencies {
         all_packages
@@ -506,15 +502,30 @@ pub fn create_bcx<'a, 'cfg>(
     )?;
 
     let mut scrape_units = match rustdoc_scrape_examples {
-        Some(scrape_filter) => {
+        Some(arg) => {
+            let filter = match arg.as_str() {
+                "all" => CompileFilter::new_all_targets(),
+                "examples" => CompileFilter::new(
+                    LibRule::False,
+                    FilterRule::none(),
+                    FilterRule::none(),
+                    FilterRule::All,
+                    FilterRule::none(),
+                ),
+                _ => {
+                    bail!(
+                        r#"-Z rustdoc-scrape-examples must take "all" or "examples" as an argument"#
+                    )
+                }
+            };
             let to_build_ids = resolve.specs_to_ids(&resolve_specs)?;
             let to_builds = pkg_set.get_many(to_build_ids)?;
             let mode = CompileMode::Docscrape;
 
             generate_targets(
                 ws,
                 &to_builds,
-                scrape_filter,
+                &filter,
                 &build_config.requested_kinds,
                 explicit_host_kind,
                 mode,

src/cargo/ops/cargo_package.rs

@@ -765,7 +765,6 @@ fn run_verify(
             target_rustc_args: rustc_args,
             local_rustdoc_args: None,
             rustdoc_document_private_items: false,
-            rustdoc_scrape_examples: None,
             honor_rust_version: true,
         },
         &exec,

src/cargo/util/command_prelude.rs

@@ -544,7 +544,6 @@ pub trait ArgMatchesExt {
             target_rustc_args: None,
             local_rustdoc_args: None,
             rustdoc_document_private_items: false,
-            rustdoc_scrape_examples: None,
             honor_rust_version: !self._is_present("ignore-rust-version"),
         };
 

src/doc/src/reference/unstable.md

@@ -1390,11 +1390,11 @@ Custom named profiles have been stabilized in the 1.57 release. See the
 * RFC: [#3123](https://github.com/rust-lang/rfcs/pull/3123)
 * Tracking Issue: [#9910](https://github.com/rust-lang/cargo/issues/9910)
 
-The `--scrape-examples` argument to the `doc` command tells Rustdoc to search
-crates in the current workspace for calls to functions. Those call-sites are then
-included as documentation. The flag can take an argument of `all` or `examples`
-which configures which crate in the workspace to analyze for examples. For instance:
+The `-Z rustdoc-scrape-examples` argument tells Rustdoc to search crates in the current workspace
+for calls to functions. Those call-sites are then included as documentation. The flag can take an
+argument of `all` or `examples` which configures which crate in the workspace to analyze for examples.
+For instance:
 
 ```
-cargo doc -Z unstable-options --scrape-examples examples
+cargo doc -Z unstable-options -Z rustdoc-scrape-examples=examples
 ```

tests/testsuite/doc.rs

@@ -2152,7 +2152,7 @@ fn doc_fingerprint_unusual_behavior() {
 #[cargo_test]
 fn scrape_examples_basic() {
     if !is_nightly() {
-        // --scrape-examples is unstable
+        // -Z rustdoc-scrape-examples is unstable
         return;
     }
 
@@ -2170,7 +2170,7 @@ fn scrape_examples_basic() {
         .file("src/lib.rs", "pub fn foo() {}\npub fn bar() { foo(); }")
         .build();
 
-    p.cargo("doc -Zunstable-options --scrape-examples all")
+    p.cargo("doc -Zunstable-options -Z rustdoc-scrape-examples=all")
         .masquerade_as_nightly_cargo()
         .with_stderr(
             "\
@@ -2192,7 +2192,7 @@ fn scrape_examples_basic() {
 #[cargo_test]
 fn scrape_examples_avoid_build_script_cycle() {
     if !is_nightly() {
-        // --scrape-examples is unstable
+        // -Z rustdoc-scrape-examples is unstable
         return;
     }
 
@@ -2231,15 +2231,15 @@ fn scrape_examples_avoid_build_script_cycle() {
         .file("bar/build.rs", "fn main(){}")
         .build();
 
-    p.cargo("doc --all -Zunstable-options --scrape-examples all")
+    p.cargo("doc --all -Zunstable-options -Z rustdoc-scrape-examples=all")
         .masquerade_as_nightly_cargo()
         .run();
 }
 
 #[cargo_test]
 fn scrape_examples_complex_reverse_dependencies() {
     if !is_nightly() {
-        // --scrape-examples is unstable
+        // -Z rustdoc-scrape-examples is unstable
         return;
     }
 
@@ -2293,7 +2293,7 @@ fn scrape_examples_complex_reverse_dependencies() {
         .file("b/src/lib.rs", "")
         .build();
 
-    p.cargo("doc -Zunstable-options --scrape-examples all")
+    p.cargo("doc -Zunstable-options -Z rustdoc-scrape-examples=all")
         .masquerade_as_nightly_cargo()
         .run();
 }