Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

rustdoc: make --passes and --no-defaults have no effect #91900

Merged
merged 1 commit into from
Dec 20, 2021
Merged

rustdoc: make --passes and --no-defaults have no effect #91900

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 21 additions & 37 deletions src/librustdoc/config.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down Expand Up @@ -128,14 +128,6 @@ crate struct Options {
crate test_builder: Option<PathBuf>,

// 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<String>,
/// Whether to run the `calculate-doc-coverage` pass, which counts the number of public items
/// with and without documentation.
crate show_coverage: bool,
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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) => {
Expand Down Expand Up @@ -710,8 +691,6 @@ impl Options {
lint_cap,
should_test,
test_args,
default_passes,
manual_passes,
show_coverage,
crate_version,
test_run_directory,
Expand Down Expand Up @@ -769,33 +748,38 @@ 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() {
if matches.opt_present(flag) {
diag.struct_warn(&format!("the `{}` flag is deprecated", flag))
.note(
"see issue #44136 <https://github.com/rust-lang/rust/issues/44136> \
for more information",
)
.emit();
}
}

let removed_flags = ["plugins", "plugin-path", "no-defaults", "passes", "input-format"];

for flag in deprecated_flags.iter() {
for &flag in removed_flags.iter() {
if matches.opt_present(flag) {
let mut err = diag.struct_warn(&format!("the `{}` flag is deprecated", flag));
let mut err = diag.struct_warn(&format!("the `{}` flag no longer functions", flag));
err.note(
"see issue #44136 <https://github.com/rust-lang/rust/issues/44136> \
for more information",
for more information",
);

if *flag == "no-defaults" {
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();
}
}

let removed_flags = ["plugins", "plugin-path"];

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();
}
}
}

/// Extracts `--extern-html-root-url` arguments from `matches` and returns a map of crate names to
Expand Down
54 changes: 12 additions & 42 deletions src/librustdoc/core.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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};

Expand Down Expand Up @@ -327,8 +327,7 @@ crate fn create_resolver<'a>(
crate fn run_global_ctxt(
tcx: TyCtxt<'_>,
resolver: Rc<RefCell<interface::BoxedResolver>>,
mut default_passes: passes::DefaultPassOption,
manual_passes: Vec<String>,
show_coverage: bool,
render_options: RenderOptions,
output_format: OutputFormat,
) -> (clean::Crate, RenderOptions, Cache) {
Expand Down Expand Up @@ -420,66 +419,38 @@ crate fn run_global_ctxt(
diag.struct_span_warn(sp, &format!("the `#![doc({})]` attribute is deprecated", name));
msg.note(
"see issue #44136 <https://github.com/rust-lang/rust/issues/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)]`");
Comment on lines +426 to +428
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ugh, not super happy that this can be configured both through attributes and a CLI flags ... but that's a fight for another day.

} else if name.starts_with("plugins") {
msg.warn("`#![doc(plugins = \"...\")]` no longer functions; see CVE-2018-1000622 <https://nvd.nist.gov/vuln/detail/CVE-2018-1000622>");
}

msg.emit();
}

let parse_pass = |name: &str, sp: Option<Span>| {
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 <https://github.com/rust-lang/rust/pull/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)));
_ => (),
}
}

Expand All @@ -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,
Expand Down
65 changes: 46 additions & 19 deletions src/librustdoc/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -274,9 +274,6 @@ fn opts() -> Vec<RustcOptGroup> {
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(
Expand Down Expand Up @@ -313,21 +310,9 @@ fn opts() -> Vec<RustcOptGroup> {
"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")
}),
Expand Down Expand Up @@ -653,6 +638,51 @@ fn opts() -> Vec<RustcOptGroup> {
"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 <https://github.com/rust-lang/rust/issues/44136> \
for more information",
"DIR",
)
}),
stable("passes", |o| {
o.optmulti(
"",
"passes",
"removed, see issue #44136 <https://github.com/rust-lang/rust/issues/44136> \
for more information",
"PASSES",
)
}),
stable("plugins", |o| {
o.optmulti(
"",
"plugins",
"removed, see issue #44136 <https://github.com/rust-lang/rust/issues/44136> \
for more information",
"PLUGINS",
)
}),
stable("no-default", |o| {
o.optflagmulti(
"",
"no-defaults",
"removed, see issue #44136 <https://github.com/rust-lang/rust/issues/44136> \
for more information",
)
}),
stable("r", |o| {
o.optopt(
"r",
"input-format",
"removed, see issue #44136 <https://github.com/rust-lang/rust/issues/44136> \
for more information",
"[rust]",
)
}),
]
}

Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -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,
)
Expand Down
22 changes: 2 additions & 20 deletions src/librustdoc/passes/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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<Pass> {
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.
Expand Down
7 changes: 3 additions & 4 deletions src/test/rustdoc-ui/deprecated-attrs.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down
Loading