From 9fb78cf698b8d87e1edcabf7d4d4ddc9d0538e75 Mon Sep 17 00:00:00 2001 From: Will Crichton Date: Fri, 29 Oct 2021 00:15:19 -0700 Subject: [PATCH] Change --scrape-examples flag to -Z rustdoc-scrape-examples --- src/bin/cargo/commands/doc.rs | 37 +------------------------------ src/cargo/core/features.rs | 4 ++++ src/cargo/ops/cargo_compile.rs | 27 +++++++++++++++------- src/cargo/ops/cargo_package.rs | 1 - src/cargo/util/command_prelude.rs | 1 - src/doc/src/reference/unstable.md | 10 ++++----- tests/testsuite/doc.rs | 12 +++++----- 7 files changed, 35 insertions(+), 57 deletions(-) diff --git a/src/bin/cargo/commands/doc.rs b/src/bin/cargo/commands/doc.rs index 7f6585688ca..875cfcfcc46 100644 --- a/src/bin/cargo/commands/doc.rs +++ b/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, diff --git a/src/cargo/core/features.rs b/src/cargo/core/features.rs index d944ba833d1..a84ff390223 100644 --- a/src/cargo/core/features.rs +++ b/src/cargo/core/features.rs @@ -654,6 +654,9 @@ unstable_cli_options!( timings: Option> = ("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 = ("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)?, diff --git a/src/cargo/ops/cargo_compile.rs b/src/cargo/ops/cargo_compile.rs index 046147f1910..392cef74085 100644 --- a/src/cargo/ops/cargo_compile.rs +++ b/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, /// 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,7 +502,22 @@ 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; @@ -514,7 +525,7 @@ pub fn create_bcx<'a, 'cfg>( generate_targets( ws, &to_builds, - scrape_filter, + &filter, &build_config.requested_kinds, explicit_host_kind, mode, diff --git a/src/cargo/ops/cargo_package.rs b/src/cargo/ops/cargo_package.rs index fe932c21fd7..48477ea25e0 100644 --- a/src/cargo/ops/cargo_package.rs +++ b/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, diff --git a/src/cargo/util/command_prelude.rs b/src/cargo/util/command_prelude.rs index 56e743d935e..d0cf17824b1 100644 --- a/src/cargo/util/command_prelude.rs +++ b/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"), }; diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md index 7fd19e3a1c7..19160662376 100644 --- a/src/doc/src/reference/unstable.md +++ b/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 ``` diff --git a/tests/testsuite/doc.rs b/tests/testsuite/doc.rs index 922a100c8ad..9e7c6e04f2f 100644 --- a/tests/testsuite/doc.rs +++ b/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,7 +2231,7 @@ 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(); } @@ -2239,7 +2239,7 @@ fn scrape_examples_avoid_build_script_cycle() { #[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(); }