From 02b94b7922d6938da3bde07cedd5f02823a72d97 Mon Sep 17 00:00:00 2001
From: Peter Jaszkowiak
Date: Mon, 13 Dec 2021 23:49:29 -0700
Subject: [PATCH] rustdoc: remove `--passes` and `--no-defaults`
- flags no longer function, see #44136
- adjust tests to match new behavior
- removed test issue-42875 (covered regression with --no-defaults)
- moved input-format to removed flags
- move all removed flags to bottom
- note flag removal in command help
- remove DefaultPassOption enum (now redundant with `show_coverage`)
---
src/librustdoc/config.rs | 62 +++++++-----------
src/librustdoc/core.rs | 54 ++++-----------
src/librustdoc/lib.rs | 65 +++++++++++++------
src/librustdoc/passes/mod.rs | 22 +------
src/test/rustdoc-ui/deprecated-attrs.rs | 7 +-
src/test/rustdoc-ui/deprecated-attrs.stderr | 20 ++----
src/test/rustdoc-ui/issue-91713.rs | 2 +-
src/test/rustdoc-ui/issue-91713.stderr | 3 +-
... => glob-extern-document-private-items.rs} | 2 +-
...=> glob-private-document-private-items.rs} | 2 +-
src/test/rustdoc/issue-15347.rs | 2 +-
src/test/rustdoc/issue-42875.rs | 13 ----
src/test/rustdoc/no-compiler-reexport.rs | 6 +-
13 files changed, 101 insertions(+), 159 deletions(-)
rename src/test/rustdoc/inline_local/{glob-extern-no-defaults.rs => glob-extern-document-private-items.rs} (90%)
rename src/test/rustdoc/inline_local/{glob-private-no-defaults.rs => glob-private-document-private-items.rs} (96%)
delete mode 100644 src/test/rustdoc/issue-42875.rs
diff --git a/src/librustdoc/config.rs b/src/librustdoc/config.rs
index 35df5fa1b74..961a98a7205 100644
--- a/src/librustdoc/config.rs
+++ b/src/librustdoc/config.rs
@@ -24,7 +24,7 @@ use crate::html::markdown::IdMap;
use crate::html::render::StylePath;
use crate::html::static_files;
use crate::opts;
-use crate::passes::{self, Condition, DefaultPassOption};
+use crate::passes::{self, Condition};
use crate::scrape_examples::{AllCallLocations, ScrapeExamplesOptions};
use crate::theme;
@@ -128,14 +128,6 @@ crate struct Options {
crate test_builder: Option,
// Options that affect the documentation process
- /// The selected default set of passes to use.
- ///
- /// Be aware: This option can come both from the CLI and from crate attributes!
- crate default_passes: DefaultPassOption,
- /// Any passes manually selected by the user.
- ///
- /// Be aware: This option can come both from the CLI and from crate attributes!
- crate manual_passes: Vec,
/// Whether to run the `calculate-doc-coverage` pass, which counts the number of public items
/// with and without documentation.
crate show_coverage: bool,
@@ -192,8 +184,6 @@ impl fmt::Debug for Options {
.field("test_args", &self.test_args)
.field("test_run_directory", &self.test_run_directory)
.field("persist_doctests", &self.persist_doctests)
- .field("default_passes", &self.default_passes)
- .field("manual_passes", &self.manual_passes)
.field("show_coverage", &self.show_coverage)
.field("crate_version", &self.crate_version)
.field("render_options", &self.render_options)
@@ -605,15 +595,6 @@ impl Options {
let show_coverage = matches.opt_present("show-coverage");
- let default_passes = if matches.opt_present("no-defaults") {
- passes::DefaultPassOption::None
- } else if show_coverage {
- passes::DefaultPassOption::Coverage
- } else {
- passes::DefaultPassOption::Default
- };
- let manual_passes = matches.opt_strs("passes");
-
let crate_types = match parse_crate_types_from_list(matches.opt_strs("crate-type")) {
Ok(types) => types,
Err(e) => {
@@ -710,8 +691,6 @@ impl Options {
lint_cap,
should_test,
test_args,
- default_passes,
- manual_passes,
show_coverage,
crate_version,
test_run_directory,
@@ -769,31 +748,36 @@ impl Options {
/// Prints deprecation warnings for deprecated options
fn check_deprecated_options(matches: &getopts::Matches, diag: &rustc_errors::Handler) {
- let deprecated_flags = ["input-format", "no-defaults", "passes"];
+ let deprecated_flags = [];
- for flag in deprecated_flags.iter() {
+ for &flag in deprecated_flags.iter() {
if matches.opt_present(flag) {
- let mut err = diag.struct_warn(&format!("the `{}` flag is deprecated", flag));
- err.note(
- "see issue #44136 \
- for more information",
- );
-
- if *flag == "no-defaults" {
- err.help("you may want to use --document-private-items");
- }
-
- err.emit();
+ diag.struct_warn(&format!("the `{}` flag is deprecated", flag))
+ .note(
+ "see issue #44136 \
+ for more information",
+ )
+ .emit();
}
}
- let removed_flags = ["plugins", "plugin-path"];
+ let removed_flags = ["plugins", "plugin-path", "no-defaults", "passes", "input-format"];
for &flag in removed_flags.iter() {
if matches.opt_present(flag) {
- diag.struct_warn(&format!("the '{}' flag no longer functions", flag))
- .warn("see CVE-2018-1000622")
- .emit();
+ let mut err = diag.struct_warn(&format!("the `{}` flag no longer functions", flag));
+ err.note(
+ "see issue #44136 \
+ for more information",
+ );
+
+ if flag == "no-defaults" || flag == "passes" {
+ err.help("you may want to use --document-private-items");
+ } else if flag == "plugins" || flag == "plugin-path" {
+ err.warn("see CVE-2018-1000622");
+ }
+
+ err.emit();
}
}
}
diff --git a/src/librustdoc/core.rs b/src/librustdoc/core.rs
index c58310947d2..5b1ff7d89d2 100644
--- a/src/librustdoc/core.rs
+++ b/src/librustdoc/core.rs
@@ -35,7 +35,7 @@ use crate::clean::inline::build_external_trait;
use crate::clean::{self, ItemId, TraitWithExtraInfo};
use crate::config::{Options as RustdocOptions, OutputFormat, RenderOptions};
use crate::formats::cache::Cache;
-use crate::passes::{self, Condition::*, ConditionalPass};
+use crate::passes::{self, Condition::*};
crate use rustc_session::config::{DebuggingOptions, Input, Options};
@@ -327,8 +327,7 @@ crate fn create_resolver<'a>(
crate fn run_global_ctxt(
tcx: TyCtxt<'_>,
resolver: Rc>,
- mut default_passes: passes::DefaultPassOption,
- manual_passes: Vec,
+ show_coverage: bool,
render_options: RenderOptions,
output_format: OutputFormat,
) -> (clean::Crate, RenderOptions, Cache) {
@@ -420,11 +419,13 @@ crate fn run_global_ctxt(
diag.struct_span_warn(sp, &format!("the `#![doc({})]` attribute is deprecated", name));
msg.note(
"see issue #44136 \
- for more information",
+ for more information",
);
if name == "no_default_passes" {
- msg.help("you may want to use `#![doc(document_private_items)]`");
+ msg.help("`#![doc(no_default_passes)]` no longer functions; you may want to use `#![doc(document_private_items)]`");
+ } else if name.starts_with("passes") {
+ msg.help("`#![doc(passes = \"...\")]` no longer functions; you may want to use `#![doc(document_private_items)]`");
} else if name.starts_with("plugins") {
msg.warn("`#![doc(plugins = \"...\")]` no longer functions; see CVE-2018-1000622 ");
}
@@ -432,54 +433,24 @@ crate fn run_global_ctxt(
msg.emit();
}
- let parse_pass = |name: &str, sp: Option| {
- if let Some(pass) = passes::find_pass(name) {
- Some(ConditionalPass::always(pass))
- } else {
- let msg = &format!("ignoring unknown pass `{}`", name);
- let mut warning = if let Some(sp) = sp {
- tcx.sess.struct_span_warn(sp, msg)
- } else {
- tcx.sess.struct_warn(msg)
- };
- if name == "collapse-docs" {
- warning.note("the `collapse-docs` pass was removed in #80261 ");
- }
- warning.emit();
- None
- }
- };
-
- let mut manual_passes: Vec<_> =
- manual_passes.into_iter().flat_map(|name| parse_pass(&name, None)).collect();
-
// Process all of the crate attributes, extracting plugin metadata along
// with the passes which we are supposed to run.
for attr in krate.module.attrs.lists(sym::doc) {
let diag = ctxt.sess().diagnostic();
let name = attr.name_or_empty();
- if attr.is_word() {
- if name == sym::no_default_passes {
- report_deprecated_attr("no_default_passes", diag, attr.span());
- if default_passes == passes::DefaultPassOption::Default {
- default_passes = passes::DefaultPassOption::None;
- }
- }
- } else if let Some(value) = attr.value_str() {
+ // `plugins = "..."`, `no_default_passes`, and `passes = "..."` have no effect
+ if attr.is_word() && name == sym::no_default_passes {
+ report_deprecated_attr("no_default_passes", diag, attr.span());
+ } else if attr.value_str().is_some() {
match name {
sym::passes => {
report_deprecated_attr("passes = \"...\"", diag, attr.span());
}
sym::plugins => {
report_deprecated_attr("plugins = \"...\"", diag, attr.span());
- continue;
}
- _ => continue,
- };
- for name in value.as_str().split_whitespace() {
- let span = attr.name_value_literal_span().unwrap_or_else(|| attr.span());
- manual_passes.extend(parse_pass(name, Some(span)));
+ _ => (),
}
}
@@ -488,10 +459,9 @@ crate fn run_global_ctxt(
}
}
- let passes = passes::defaults(default_passes).iter().copied().chain(manual_passes);
info!("Executing passes");
- for p in passes {
+ for p in passes::defaults(show_coverage) {
let run = match p.condition {
Always => true,
WhenDocumentPrivate => ctxt.render_options.document_private,
diff --git a/src/librustdoc/lib.rs b/src/librustdoc/lib.rs
index 8699ab20b19..9a704bc3d87 100644
--- a/src/librustdoc/lib.rs
+++ b/src/librustdoc/lib.rs
@@ -274,9 +274,6 @@ fn opts() -> Vec {
stable("h", |o| o.optflagmulti("h", "help", "show this help message")),
stable("V", |o| o.optflagmulti("V", "version", "print rustdoc's version")),
stable("v", |o| o.optflagmulti("v", "verbose", "use verbose output")),
- stable("r", |o| {
- o.optopt("r", "input-format", "the input type of the specified file", "[rust]")
- }),
stable("w", |o| o.optopt("w", "output-format", "the output type to write", "[html]")),
stable("output", |o| {
o.optopt(
@@ -313,21 +310,9 @@ fn opts() -> Vec {
"give precedence to `--extern-html-root-url`, not `html_root_url`",
)
}),
- stable("plugin-path", |o| o.optmulti("", "plugin-path", "removed", "DIR")),
stable("C", |o| {
o.optmulti("C", "codegen", "pass a codegen option to rustc", "OPT[=VALUE]")
}),
- stable("passes", |o| {
- o.optmulti(
- "",
- "passes",
- "list of passes to also run, you might want to pass it multiple times; a value of \
- `list` will print available passes",
- "PASSES",
- )
- }),
- stable("plugins", |o| o.optmulti("", "plugins", "removed", "PLUGINS")),
- stable("no-default", |o| o.optflagmulti("", "no-defaults", "don't run the default passes")),
stable("document-private-items", |o| {
o.optflagmulti("", "document-private-items", "document private items")
}),
@@ -653,6 +638,51 @@ fn opts() -> Vec {
"path to function call information (for displaying examples in the documentation)",
)
}),
+ // deprecated / removed options
+ stable("plugin-path", |o| {
+ o.optmulti(
+ "",
+ "plugin-path",
+ "removed, see issue #44136 \
+ for more information",
+ "DIR",
+ )
+ }),
+ stable("passes", |o| {
+ o.optmulti(
+ "",
+ "passes",
+ "removed, see issue #44136 \
+ for more information",
+ "PASSES",
+ )
+ }),
+ stable("plugins", |o| {
+ o.optmulti(
+ "",
+ "plugins",
+ "removed, see issue #44136 \
+ for more information",
+ "PLUGINS",
+ )
+ }),
+ stable("no-default", |o| {
+ o.optflagmulti(
+ "",
+ "no-defaults",
+ "removed, see issue #44136 \
+ for more information",
+ )
+ }),
+ stable("r", |o| {
+ o.optopt(
+ "r",
+ "input-format",
+ "removed, see issue #44136 \
+ for more information",
+ "[rust]",
+ )
+ }),
]
}
@@ -761,11 +791,9 @@ fn main_options(options: config::Options) -> MainResult {
// plug/cleaning passes.
let crate_version = options.crate_version.clone();
- let default_passes = options.default_passes;
let output_format = options.output_format;
// FIXME: fix this clone (especially render_options)
let externs = options.externs.clone();
- let manual_passes = options.manual_passes.clone();
let render_options = options.render_options.clone();
let scrape_examples_options = options.scrape_examples_options.clone();
let config = core::create_config(options);
@@ -796,8 +824,7 @@ fn main_options(options: config::Options) -> MainResult {
core::run_global_ctxt(
tcx,
resolver,
- default_passes,
- manual_passes,
+ show_coverage,
render_options,
output_format,
)
diff --git a/src/librustdoc/passes/mod.rs b/src/librustdoc/passes/mod.rs
index 99ac87db4ff..2c2bf2b8c0f 100644
--- a/src/librustdoc/passes/mod.rs
+++ b/src/librustdoc/passes/mod.rs
@@ -125,27 +125,9 @@ impl ConditionalPass {
}
}
-/// A shorthand way to refer to which set of passes to use, based on the presence of
-/// `--no-defaults` and `--show-coverage`.
-#[derive(Copy, Clone, PartialEq, Eq, Debug)]
-crate enum DefaultPassOption {
- Default,
- Coverage,
- None,
-}
-
/// Returns the given default set of passes.
-crate fn defaults(default_set: DefaultPassOption) -> &'static [ConditionalPass] {
- match default_set {
- DefaultPassOption::Default => DEFAULT_PASSES,
- DefaultPassOption::Coverage => COVERAGE_PASSES,
- DefaultPassOption::None => &[],
- }
-}
-
-/// If the given name matches a known pass, returns its information.
-crate fn find_pass(pass_name: &str) -> Option {
- PASSES.iter().find(|p| p.name == pass_name).copied()
+crate fn defaults(show_coverage: bool) -> &'static [ConditionalPass] {
+ if show_coverage { COVERAGE_PASSES } else { DEFAULT_PASSES }
}
/// Returns a span encompassing all the given attributes.
diff --git a/src/test/rustdoc-ui/deprecated-attrs.rs b/src/test/rustdoc-ui/deprecated-attrs.rs
index 5febc5eb9cd..4f6a14fc2c2 100644
--- a/src/test/rustdoc-ui/deprecated-attrs.rs
+++ b/src/test/rustdoc-ui/deprecated-attrs.rs
@@ -1,16 +1,15 @@
// check-pass
// compile-flags: --passes unknown-pass
-// error-pattern: ignoring unknown pass `unknown-pass`
+// error-pattern: the `passes` flag no longer functions
#![doc(no_default_passes)]
//~^ WARNING attribute is deprecated
//~| NOTE see issue #44136
-//~| HELP use `#![doc(document_private_items)]`
+//~| HELP no longer functions; you may want to use `#![doc(document_private_items)]`
#![doc(passes = "collapse-docs unindent-comments")]
//~^ WARNING attribute is deprecated
//~| NOTE see issue #44136
-//~| WARNING ignoring unknown pass
-//~| NOTE `collapse-docs` pass was removed
+//~| HELP no longer functions; you may want to use `#![doc(document_private_items)]`
#![doc(plugins = "xxx")]
//~^ WARNING attribute is deprecated
//~| NOTE see issue #44136
diff --git a/src/test/rustdoc-ui/deprecated-attrs.stderr b/src/test/rustdoc-ui/deprecated-attrs.stderr
index b855cedf522..45b20ce70ef 100644
--- a/src/test/rustdoc-ui/deprecated-attrs.stderr
+++ b/src/test/rustdoc-ui/deprecated-attrs.stderr
@@ -1,8 +1,7 @@
-warning: the `passes` flag is deprecated
+warning: the `passes` flag no longer functions
|
= note: see issue #44136 for more information
-
-warning: ignoring unknown pass `unknown-pass`
+ = help: you may want to use --document-private-items
warning: the `#![doc(no_default_passes)]` attribute is deprecated
--> $DIR/deprecated-attrs.rs:5:8
@@ -11,7 +10,7 @@ LL | #![doc(no_default_passes)]
| ^^^^^^^^^^^^^^^^^
|
= note: see issue #44136 for more information
- = help: you may want to use `#![doc(document_private_items)]`
+ = help: `#![doc(no_default_passes)]` no longer functions; you may want to use `#![doc(document_private_items)]`
warning: the `#![doc(passes = "...")]` attribute is deprecated
--> $DIR/deprecated-attrs.rs:9:8
@@ -20,17 +19,10 @@ LL | #![doc(passes = "collapse-docs unindent-comments")]
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
= note: see issue #44136 for more information
-
-warning: ignoring unknown pass `collapse-docs`
- --> $DIR/deprecated-attrs.rs:9:17
- |
-LL | #![doc(passes = "collapse-docs unindent-comments")]
- | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- |
- = note: the `collapse-docs` pass was removed in #80261
+ = help: `#![doc(passes = "...")]` no longer functions; you may want to use `#![doc(document_private_items)]`
warning: the `#![doc(plugins = "...")]` attribute is deprecated
- --> $DIR/deprecated-attrs.rs:14:8
+ --> $DIR/deprecated-attrs.rs:13:8
|
LL | #![doc(plugins = "xxx")]
| ^^^^^^^^^^^^^^^
@@ -38,5 +30,5 @@ LL | #![doc(plugins = "xxx")]
= note: see issue #44136 for more information
= warning: `#![doc(plugins = "...")]` no longer functions; see CVE-2018-1000622
-warning: 5 warnings emitted
+warning: 3 warnings emitted
diff --git a/src/test/rustdoc-ui/issue-91713.rs b/src/test/rustdoc-ui/issue-91713.rs
index b7057d868c2..610bbf11d9c 100644
--- a/src/test/rustdoc-ui/issue-91713.rs
+++ b/src/test/rustdoc-ui/issue-91713.rs
@@ -1,3 +1,3 @@
// check-pass
// compile-flags: --passes list
-// error-pattern: the `passes` flag is deprecated
+// error-pattern: the `passes` flag no longer functions
diff --git a/src/test/rustdoc-ui/issue-91713.stderr b/src/test/rustdoc-ui/issue-91713.stderr
index 70c22b3c01e..44ead7a1de2 100644
--- a/src/test/rustdoc-ui/issue-91713.stderr
+++ b/src/test/rustdoc-ui/issue-91713.stderr
@@ -1,4 +1,5 @@
-warning: the `passes` flag is deprecated
+warning: the `passes` flag no longer functions
|
= note: see issue #44136 for more information
+ = help: you may want to use --document-private-items
diff --git a/src/test/rustdoc/inline_local/glob-extern-no-defaults.rs b/src/test/rustdoc/inline_local/glob-extern-document-private-items.rs
similarity index 90%
rename from src/test/rustdoc/inline_local/glob-extern-no-defaults.rs
rename to src/test/rustdoc/inline_local/glob-extern-document-private-items.rs
index 55c75dfe27b..a2f0d65efce 100644
--- a/src/test/rustdoc/inline_local/glob-extern-no-defaults.rs
+++ b/src/test/rustdoc/inline_local/glob-extern-document-private-items.rs
@@ -1,4 +1,4 @@
-// compile-flags: --no-defaults
+// compile-flags: --document-private-items
#![crate_name = "foo"]
diff --git a/src/test/rustdoc/inline_local/glob-private-no-defaults.rs b/src/test/rustdoc/inline_local/glob-private-document-private-items.rs
similarity index 96%
rename from src/test/rustdoc/inline_local/glob-private-no-defaults.rs
rename to src/test/rustdoc/inline_local/glob-private-document-private-items.rs
index ac854ac4320..f16d21ecdb1 100644
--- a/src/test/rustdoc/inline_local/glob-private-no-defaults.rs
+++ b/src/test/rustdoc/inline_local/glob-private-document-private-items.rs
@@ -1,4 +1,4 @@
-// compile-flags: --no-defaults
+// compile-flags: --document-private-items
#![crate_name = "foo"]
diff --git a/src/test/rustdoc/issue-15347.rs b/src/test/rustdoc/issue-15347.rs
index fa67da840b7..e93d7401168 100644
--- a/src/test/rustdoc/issue-15347.rs
+++ b/src/test/rustdoc/issue-15347.rs
@@ -1,4 +1,4 @@
-// compile-flags: --no-defaults --passes collapse-docs --passes unindent-comments
+// compile-flags: -Z unstable-options --document-hidden-items
// @has issue_15347/fn.foo.html
#[doc(hidden)]
diff --git a/src/test/rustdoc/issue-42875.rs b/src/test/rustdoc/issue-42875.rs
deleted file mode 100644
index 292c2077688..00000000000
--- a/src/test/rustdoc/issue-42875.rs
+++ /dev/null
@@ -1,13 +0,0 @@
-// compile-flags: --no-defaults
-
-#![crate_name = "foo"]
-
-// @has foo/a/index.html '//code' 'use *;'
-mod a {
- use *;
-}
-
-// @has foo/b/index.html '//code' 'pub use *;'
-pub mod b {
- pub use *;
-}
diff --git a/src/test/rustdoc/no-compiler-reexport.rs b/src/test/rustdoc/no-compiler-reexport.rs
index 6d50325fed5..d28fdf87b77 100644
--- a/src/test/rustdoc/no-compiler-reexport.rs
+++ b/src/test/rustdoc/no-compiler-reexport.rs
@@ -1,7 +1,7 @@
-// compile-flags: --no-defaults
+// compile-flags: -Z unstable-options --document-hidden-items --document-private-items
#![crate_name = "foo"]
-// @has 'foo/index.html' '//code' 'extern crate std;'
-// @!has 'foo/index.html' '//code' 'use std::prelude::v1::*;'
+// @!has 'foo/index.html' '//code' 'extern crate std;'
+// @!has 'foo/index.html' '//code' 'use std::prelude'
pub struct Foo;