rust-lang/rust
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Rollup merge of #67875 - dtolnay:hidden, r=GuillaumeGomez

Browse Source 
Distinguish between private items and hidden items in rustdoc

I believe rustdoc should not be conflating private items (visibility lower than `pub`) and hidden items (attribute `doc(hidden)`). This matters now that Cargo is passing --document-private-items by default for bin crates. In bin crates that rely on macros, intentionally hidden implementation details of the macros can overwhelm the actual useful internal API that one would want to document.

This PR restores the strip-hidden pass when documenting private items, and introduces a separate unstable --document-hidden-items option to skip the strip-hidden pass. The two options are orthogonal to one another.

Fixes #67851. Closes #60884.
This commit is contained in:
Yuki Okushi
2020-01-09 00:29:13 +09:00
committed by GitHub
parent 429a7e7522 90adafbc9e
commit 03fe834a23
20 changed files with 139 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
src/librustdoc/core.rs
View File

@@ -33,7 +33,7 @@ use crate::clean::{AttributesExt, MAX_DEF_ID};
use crate::config::{Options as RustdocOptions, RenderOptions};
use crate::html::render::RenderInfo;
use crate::passes;
use crate::passes::{self, Condition::*, ConditionalPass};
pub use rustc::session::config::{CodegenOptions, DebuggingOptions, Input, Options};
pub use rustc::session::search_paths::SearchPath;
@@ -221,6 +221,8 @@ pub fn run_core(options: RustdocOptions) -> (clean::Crate, RenderInfo, RenderOpt
describe_lints,
lint_cap,
mut default_passes,
mut document_private,
document_hidden,
mut manual_passes,
display_warnings,
render_options,
@@ -457,16 +459,14 @@ pub fn run_core(options: RustdocOptions) -> (clean::Crate, RenderInfo, RenderOpt
}
if attr.is_word() && name == sym::document_private_items {
if default_passes == passes::DefaultPassOption::Default {
default_passes = passes::DefaultPassOption::Private;
}
document_private = true;
}
}
let passes = passes::defaults(default_passes).iter().chain(
let passes = passes::defaults(default_passes).iter().copied().chain(
manual_passes.into_iter().flat_map(|name| {
if let Some(pass) = passes::find_pass(&name) {
Some(pass)
Some(ConditionalPass::always(pass))
} else {
error!("unknown pass {}, skipping", name);
None
@@ -476,9 +476,17 @@ pub fn run_core(options: RustdocOptions) -> (clean::Crate, RenderInfo, RenderOpt
info!("Executing passes");
for pass in passes {
debug!("running pass {}", pass.name);
krate = (pass.pass)(krate, &ctxt);
for p in passes {
let run = match p.condition {
Always => true,
WhenDocumentPrivate => document_private,
WhenNotDocumentPrivate => !document_private,
WhenNotDocumentHidden => !document_hidden,
};
if run {
debug!("running pass {}", p.pass.name);
krate = (p.pass.run)(krate, &ctxt);
}
}
ctxt.sess().abort_if_errors();