Skip to content

Commit ed39b93

Browse files
authored
Rollup merge of rust-lang#55804 - QuietMisdreavus:eager-crate-inline, r=pnkfelix
rustdoc: don't inline `pub use some_crate` unless directly asked to cc rust-lang#52509 (fixes it? i'm not sure about my comment summoning the docs team) When rustdoc encounters a `pub use` statement for an item from another crate, it will eagerly inline its contents into your crate. This somewhat clashes with the new paths behavior in Rust 2018, in which crates are implicitly linked and re-exported with `pub use` instead of `pub extern crate`. In rust 2015, `pub extern crate` would only create a single line for its re-export in the docs, so i'm making it do the same with `pub use some_crate;`. The exact new behavior is like this: *If rustdoc sees a `pub use` statement, and the item being imported is the root of another crate, it will only inline it if `#[doc(inline)]` is provided.* I made it only avoid crate roots because otherwise it would stop inlining any module, which may or may not be what people want.
2 parents e9376b7 + 401cb6b commit ed39b93

File tree

6 files changed

+81
-1
lines changed

6 files changed

+81
-1
lines changed

src/doc/rustdoc/src/the-doc-attribute.md

+3
Original file line numberDiff line numberDiff line change
@@ -186,6 +186,9 @@ mod bar {
186186

187187
Now we'll have a `Re-exports` line, and `Bar` will not link to anywhere.
188188

189+
One special case: In Rust 2018 and later, if you `pub use` one of your dependencies, `rustdoc` will
190+
not eagerly inline it as a module unless you add `#[doc(inline)}`.
191+
189192
## `#[doc(hidden)]`
190193

191194
Any item annotated with `#[doc(hidden)]` will not appear in the documentation, unless

src/librustdoc/clean/mod.rs

+14-1
Original file line numberDiff line numberDiff line change
@@ -3499,13 +3499,16 @@ impl Clean<Vec<Item>> for doctree::Import {
34993499
// forcefully don't inline if this is not public or if the
35003500
// #[doc(no_inline)] attribute is present.
35013501
// Don't inline doc(hidden) imports so they can be stripped at a later stage.
3502-
let denied = !self.vis.node.is_pub() || self.attrs.iter().any(|a| {
3502+
let mut denied = !self.vis.node.is_pub() || self.attrs.iter().any(|a| {
35033503
a.name() == "doc" && match a.meta_item_list() {
35043504
Some(l) => attr::list_contains_name(&l, "no_inline") ||
35053505
attr::list_contains_name(&l, "hidden"),
35063506
None => false,
35073507
}
35083508
});
3509+
// Also check whether imports were asked to be inlined, in case we're trying to re-export a
3510+
// crate in Rust 2018+
3511+
let please_inline = self.attrs.lists("doc").has_word("inline");
35093512
let path = self.path.clean(cx);
35103513
let inner = if self.glob {
35113514
if !denied {
@@ -3518,6 +3521,16 @@ impl Clean<Vec<Item>> for doctree::Import {
35183521
Import::Glob(resolve_use_source(cx, path))
35193522
} else {
35203523
let name = self.name;
3524+
if !please_inline {
3525+
match path.def {
3526+
Def::Mod(did) => if !did.is_local() && did.index == CRATE_DEF_INDEX {
3527+
// if we're `pub use`ing an extern crate root, don't inline it unless we
3528+
// were specifically asked for it
3529+
denied = true;
3530+
}
3531+
_ => {}
3532+
}
3533+
}
35213534
if !denied {
35223535
let mut visited = FxHashSet::default();
35233536
if let Some(items) = inline::try_inline(cx, path.def, name, &mut visited) {
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
// Copyright 2018 The Rust Project Developers. See the COPYRIGHT
2+
// file at the top-level directory of this distribution and at
3+
// http://rust-lang.org/COPYRIGHT.
4+
//
5+
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6+
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7+
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8+
// option. This file may not be copied, modified, or distributed
9+
// except according to those terms.
10+
11+
pub mod asdf {
12+
pub struct SomeStruct;
13+
}
14+
15+
pub trait SomeTrait {}
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
// Copyright 2018 The Rust Project Developers. See the COPYRIGHT
2+
// file at the top-level directory of this distribution and at
3+
// http://rust-lang.org/COPYRIGHT.
4+
//
5+
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6+
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7+
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8+
// option. This file may not be copied, modified, or distributed
9+
// except according to those terms.
10+
11+
pub struct SomethingElse;
+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
// Copyright 2018 The Rust Project Developers. See the COPYRIGHT
2+
// file at the top-level directory of this distribution and at
3+
// http://rust-lang.org/COPYRIGHT.
4+
//
5+
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6+
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7+
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8+
// option. This file may not be copied, modified, or distributed
9+
// except according to those terms.
10+
11+
// aux-build:use_crate.rs
12+
// aux-build:use_crate_2.rs
13+
// build-aux-docs
14+
// edition:2018
15+
// compile-flags:--extern use_crate --extern use_crate_2 -Z unstable-options
16+
17+
// During the buildup to Rust 2018, rustdoc would eagerly inline `pub use some_crate;` as if it
18+
// were a module, so we changed it to make `pub use`ing crate roots remain as a `pub use` statement
19+
// in docs... unless you added `#[doc(inline)]`.
20+
21+
#![crate_name = "local"]
22+
23+
// @!has-dir local/use_crate
24+
// @has local/index.html
25+
// @has - '//code' 'pub use use_crate'
26+
pub use use_crate;
27+
28+
// @has-dir local/asdf
29+
// @has local/asdf/index.html
30+
// @has local/index.html '//a/@href' 'asdf/index.html'
31+
pub use use_crate::asdf;
32+
33+
// @has-dir local/use_crate_2
34+
// @has local/use_crate_2/index.html
35+
// @has local/index.html '//a/@href' 'use_crate_2/index.html'
36+
#[doc(inline)]
37+
pub use use_crate_2;

src/test/rustdoc/src-links-external.rs

+1
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
extern crate src_links_external;
1919

2020
// @has foo/bar/index.html '//a/@href' '../../src/src_links_external/src-links-external.rs.html#11'
21+
#[doc(inline)]
2122
pub use src_links_external as bar;
2223

2324
// @has foo/bar/struct.Foo.html '//a/@href' '../../src/src_links_external/src-links-external.rs.html#11'

0 commit comments

Comments
 (0)