rustdoc: Allow inlining of reexported crates and crate items

[panicbit]

#[doc(inline)]
pub extern crate foo;

Could show foo as if it was a module.

extern crate foo;
#[doc(inline)]
pub use foo::*;

Could inline the reexported items as if foo was a module.

[QuietMisdreavus]

Some mentoring notes. I'm planning on walking @DebugSteven through this.

First, this is only relevant for 2015 edition, since 2018 edition won't have it as an extern crate anyway. However, this issue is still relevant for 2015 code, so let's take a look...

The relevant spot where extern crate statements are processed is in clean/mod.rs:

rust/src/librustdoc/clean/mod.rs

Lines 3506 to 3519 in 6ecad33

	impl Clean<Item> for doctree::ExternCrate {
	fn clean(&self, cx: &DocContext) -> Item {
	Item {
	name: None,
	attrs: self.attrs.clean(cx),
	source: self.whence.clean(cx),
	def_id: DefId { krate: self.cnum, index: CRATE_DEF_INDEX },
	visibility: self.vis.clean(cx),
	stability: None,
	deprecation: None,
	inner: ExternCrateItem(self.name.clean(cx), self.path.clone())
	}
	}
	}

Fortunately, the spot where use statements are processed is right below it! We need to copy some code from this to make sure we do the same thing.

The rough idea i have for the new code goes like this:

• Change this Clean impl to return a Vec<Item> instead of a single Item.
• Check the ExternCrate to make sure it's pub and is marked with #[doc(inline)]. If it is, attempt to inline it by calling inline::try_inline. If it succeeds, return the list of new items.
• If we didn't try inlining or it failed (by returning None), create the single Item as before, stick it in a Vec, and return that instead.

That middle part is where it gets interesting, because try_inline assumes we have a Def on hand from the Import. Fortunately, we can effectively make one up on the spot, since we have the CrateNum on hand and we can make up a DefId that points to the crate root. Once we have that, all we need is to wrap it with Def::Mod since we know we're pointing at a module:

Def::Mod(DefId {
    krate: self.cnum,
    index: CRATE_DEF_INDEX,
})

All the rest of the arguments to try_inline are already on hand or can be created on the spot.

---

To check the extern crate statement for the right conditions, we can copy code from the doctree::Import impl:

rust/src/librustdoc/clean/mod.rs

Lines 3527 to 3533 in 6ecad33

	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,
	}
	});

This is performing similar checks to what we need, though we'll need to tweak them slightly. The ExternCrate type has the same vis and attrs fields, so we can use the same structure to check for whether it's pub and for inspecting the attributes. Note that that code is checking for whether it shouldn't inline a use statement, so it's checking for whether it's non-pub or whether it has #[doc(no_inline)] or #[doc(hidden)]. However, we want to check for whether we should inline our statement, so we want to check for #[doc(inline)]. The same check can be used, but the two inner statements can be replaced with one, to compare against "inline".