Skip to content

Commit

Permalink
Auto merge of #52751 - QuietMisdreavus:you-shall-not-pass, r=Guillaum…
Browse files Browse the repository at this point in the history
…eGomez

rustdoc: rework how default passes are chosen

This is a refactor that changes how we select default passes, and changes the set of passes used for `--document-private-items`. It's groundwork for a bigger refactor i want to do.

The major changes:

* There are now two sets of "default passes": one set for "no flags given" and one for "document private items".
* These sets can be selected by a new `DefaultPassOption` enum, which is selected from based on the presence of `--no-defaults` or `--document-private-items` CLI flags, or their associated crate attributes.
* When printing the list of passes, we also print the list of passes for `--document-private-items` in addition to the "default defaults".
* I added `propagate-doc-cfg` and `strip-priv-imports` to the "document private items" set. The former is to ensure items are properly tagged with the full set of cfg flags even when "document private items" is active. The latter is based on feedback and personal experience navigating the `rustc` docs, which use that flag. `strip-priv-imports` only removes non-pub `use` statements, so it should be harmless from a documentation standpoint to remove those items from "private items" documentation.
  • Loading branch information
bors committed Jul 29, 2018
2 parents 6a2c97c + 0db4317 commit fb0653e
Show file tree
Hide file tree
Showing 2 changed files with 50 additions and 26 deletions.
49 changes: 23 additions & 26 deletions src/librustdoc/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -373,6 +373,10 @@ pub fn main_args(args: &[String]) -> isize {
for &name in passes::DEFAULT_PASSES {
println!("{:>20}", name);
}
println!("\nPasses run with `--document-private-items`:");
for &name in passes::DEFAULT_PRIVATE_PASSES {
println!("{:>20}", name);
}
return 0;
}

Expand Down Expand Up @@ -623,20 +627,16 @@ fn rust_input<R, F>(cratefile: PathBuf,
where R: 'static + Send,
F: 'static + Send + FnOnce(Output) -> R
{
let mut default_passes = !matches.opt_present("no-defaults");
let mut passes = matches.opt_strs("passes");
let mut plugins = matches.opt_strs("plugins");

// We hardcode in the passes here, as this is a new flag and we
// are generally deprecating passes.
if matches.opt_present("document-private-items") {
default_passes = false;
let mut default_passes = if matches.opt_present("no-defaults") {
passes::DefaultPassOption::None
} else if matches.opt_present("document-private-items") {
passes::DefaultPassOption::Private
} else {
passes::DefaultPassOption::Default
};

passes = vec![
String::from("collapse-docs"),
String::from("unindent-comments"),
];
}
let mut manual_passes = matches.opt_strs("passes");
let mut plugins = matches.opt_strs("plugins");

// First, parse the crate and extract all relevant information.
let mut paths = SearchPaths::new();
Expand Down Expand Up @@ -706,13 +706,15 @@ where R: 'static + Send,
if attr.is_word() {
if name == Some("no_default_passes") {
report_deprecated_attr("no_default_passes", &diag);
default_passes = false;
if default_passes == passes::DefaultPassOption::Default {
default_passes = passes::DefaultPassOption::None;
}
}
} else if let Some(value) = attr.value_str() {
let sink = match name {
Some("passes") => {
report_deprecated_attr("passes = \"...\"", &diag);
&mut passes
&mut manual_passes
},
Some("plugins") => {
report_deprecated_attr("plugins = \"...\"", &diag);
Expand All @@ -726,20 +728,15 @@ where R: 'static + Send,
}

if attr.is_word() && name == Some("document_private_items") {
default_passes = false;

passes = vec![
String::from("collapse-docs"),
String::from("unindent-comments"),
];
if default_passes == passes::DefaultPassOption::Default {
default_passes = passes::DefaultPassOption::Private;
}
}
}

if default_passes {
for name in passes::DEFAULT_PASSES.iter().rev() {
passes.insert(0, name.to_string());
}
}
let mut passes: Vec<String> =
passes::defaults(default_passes).iter().map(|p| p.to_string()).collect();
passes.extend(manual_passes);

if !plugins.is_empty() {
eprintln!("WARNING: --plugins no longer functions; see CVE-2018-1000622");
Expand Down
27 changes: 27 additions & 0 deletions src/librustdoc/passes/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,33 @@ pub const DEFAULT_PASSES: &'static [&'static str] = &[
"propagate-doc-cfg",
];

pub const DEFAULT_PRIVATE_PASSES: &'static [&'static str] = &[
"strip-priv-imports",
"collapse-docs",
"unindent-comments",
"propagate-doc-cfg",
];

#[derive(Copy, Clone, PartialEq, Eq, Debug)]
pub enum DefaultPassOption {
Default,
Private,
None,
}

pub fn defaults(default_set: DefaultPassOption) -> &'static [&'static str] {
match default_set {
DefaultPassOption::Default => {
DEFAULT_PASSES
},
DefaultPassOption::Private => {
DEFAULT_PRIVATE_PASSES
},
DefaultPassOption::None => {
&[]
},
}
}

struct Stripper<'a> {
retained: &'a mut DefIdSet,
Expand Down

0 comments on commit fb0653e

Please sign in to comment.