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.

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

@@ -186,6 +186,9 @@ mod bar {
 
 Now we'll have a `Re-exports` line, and `Bar` will not link to anywhere.
 
+One special case: In Rust 2018 and later, if you `pub use` one of your dependencies, `rustdoc` will
+not eagerly inline it as a module unless you add `#[doc(inline)}`.
+
 ## `#[doc(hidden)]`
 
 Any item annotated with `#[doc(hidden)]` will not appear in the documentation, unless

src/librustdoc/clean/mod.rs

@@ -3499,13 +3499,16 @@ impl Clean<Vec<Item>> for doctree::Import {
         // forcefully don't inline if this is not public or if the
         // #[doc(no_inline)] attribute is present.
         // Don't inline doc(hidden) imports so they can be stripped at a later stage.
-        let denied = !self.vis.node.is_pub() || self.attrs.iter().any(|a| {
+        let mut denied = !self.vis.node.is_pub() || self.attrs.iter().any(|a| {
             a.name() == "doc" && match a.meta_item_list() {
                 Some(l) => attr::list_contains_name(&l, "no_inline") ||
                            attr::list_contains_name(&l, "hidden"),
                 None => false,
             }
         });
+        // Also check whether imports were asked to be inlined, in case we're trying to re-export a
+        // crate in Rust 2018+
+        let please_inline = self.attrs.lists("doc").has_word("inline");
         let path = self.path.clean(cx);
         let inner = if self.glob {
             if !denied {
@@ -3518,6 +3521,16 @@ impl Clean<Vec<Item>> for doctree::Import {
             Import::Glob(resolve_use_source(cx, path))
         } else {
             let name = self.name;
+            if !please_inline {
+                match path.def {
+                    Def::Mod(did) => if !did.is_local() && did.index == CRATE_DEF_INDEX {
+                        // if we're `pub use`ing an extern crate root, don't inline it unless we
+                        // were specifically asked for it
+                        denied = true;
+                    }
+                    _ => {}
+                }
+            }
             if !denied {
                 let mut visited = FxHashSet::default();
                 if let Some(items) = inline::try_inline(cx, path.def, name, &mut visited) {

src/test/rustdoc/inline_cross/auxiliary/use_crate.rs

@@ -0,0 +1,15 @@
+// Copyright 2018 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+pub mod asdf {
+    pub struct SomeStruct;
+}
+
+pub trait SomeTrait {}

src/test/rustdoc/inline_cross/auxiliary/use_crate_2.rs

@@ -0,0 +1,11 @@
+// Copyright 2018 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+pub struct SomethingElse;

src/test/rustdoc/inline_cross/use_crate.rs

@@ -0,0 +1,37 @@
+// Copyright 2018 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+// aux-build:use_crate.rs
+// aux-build:use_crate_2.rs
+// build-aux-docs
+// edition:2018
+// compile-flags:--extern use_crate --extern use_crate_2 -Z unstable-options
+
+// During the buildup to Rust 2018, rustdoc would eagerly inline `pub use some_crate;` as if it
+// were a module, so we changed it to make `pub use`ing crate roots remain as a `pub use` statement
+// in docs... unless you added `#[doc(inline)]`.
+
+#![crate_name = "local"]
+
+// @!has-dir local/use_crate
+// @has local/index.html
+// @has - '//code' 'pub use use_crate'
+pub use use_crate;
+
+// @has-dir local/asdf
+// @has local/asdf/index.html
+// @has local/index.html '//a/@href' 'asdf/index.html'
+pub use use_crate::asdf;
+
+// @has-dir local/use_crate_2
+// @has local/use_crate_2/index.html
+// @has local/index.html '//a/@href' 'use_crate_2/index.html'
+#[doc(inline)]
+pub use use_crate_2;

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

@@ -18,6 +18,7 @@
 extern crate src_links_external;
 
 // @has foo/bar/index.html '//a/@href' '../../src/src_links_external/src-links-external.rs.html#11'
+#[doc(inline)]
 pub use src_links_external as bar;
 
 // @has foo/bar/struct.Foo.html '//a/@href' '../../src/src_links_external/src-links-external.rs.html#11'