Skip to content

Commit

Permalink
Auto merge of #91900 - pitaj:fix-91714, r=jyn514
Browse files Browse the repository at this point in the history 
rustdoc: make `--passes` and `--no-defaults` have no effect

Fixes #91714

One potential issue is that currently there is no stable way to achieve `--document-hidden-items`. This affects test `issue-15347`.

I also had to modify the tests `issue-42875` and `no-compiler-export`. Regardless of combinations of `--document-hidden-items` and `--document-private-items`, I was unable to get these to pass without the modifications. I left behind a comment noting the change.
  • Loading branch information
@bors
bors committed Dec 20, 2021
2 parents ed7a206 + 02b94b7 commit 940a97a
Show file tree
Hide file tree
Showing 13 changed files with 99 additions and 157 deletions.
58 changes: 21 additions & 37 deletions src/librustdoc/config.rs
View file
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
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)]`");
} 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
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
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
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

0 comments on commit 940a97a

Please sign in to comment.