From bc9e0820e74333b0f578d63939c9ab25bc196a1e Mon Sep 17 00:00:00 2001
From: steveklabnik <steve@steveklabnik.com>
Date: Thu, 10 Aug 2017 18:52:10 -0400
Subject: [PATCH] doc doc(inline) and doc(no_inline)

---
 src/doc/rustdoc/src/the-doc-attribute.md | 58 +++++++++++++++++++++++-
 1 file changed, 57 insertions(+), 1 deletion(-)

diff --git a/src/doc/rustdoc/src/the-doc-attribute.md b/src/doc/rustdoc/src/the-doc-attribute.md
index 18a1814938a08..013eccab04ebb 100644
--- a/src/doc/rustdoc/src/the-doc-attribute.md
+++ b/src/doc/rustdoc/src/the-doc-attribute.md
@@ -94,7 +94,63 @@ it will not.
 These forms of the `#[doc]` attribute are used on individual items, to control how
 they are documented.
 
-## `#[doc(no_inline)]`
+## `#[doc(no_inline)]`/`#[doc(inline)]`
+
+These attributes are used on `use` statements, and control where the documentation shows
+up. For example, consider this Rust code:
+
+```rust
+pub use bar::Bar;
+
+/// bar docs
+pub mod bar {
+    /// the docs for Bar
+    pub struct Bar;
+}
+```
+
+The documentation will generate a "Reexports" section, and say `pub use bar::Bar;`, where
+`Bar` is a link to its page.
+
+If we change the `use` line like this:
+
+```rust,ignore
+#[doc(inline)]
+pub use bar::Bar;
+```
+
+Instead, `Bar` will appear in a `Structs` section, just like `Bar` was defined at the
+top level, rather than `pub use`'d.
+
+Let's change our original example, by making `bar` private:
+
+```rust
+pub use bar::Bar;
+
+/// bar docs
+mod bar {
+    /// the docs for Bar
+    pub struct Bar;
+}
+```
+
+Here, because `bar` is not public, `Bar` wouldn't have its own page, so there's nowhere
+to link to. `rustdoc` will inline these definitions, and so we end up in the same case
+as the `#[doc(inline)]` above; `Bar` is in a `Structs` section, as if it were defined at
+the top level. If we add the `no_inline` form of the attribute:
+
+```rust
+#[doc(no_inline)]
+pub use bar::Bar;
+
+/// bar docs
+mod bar {
+    /// the docs for Bar
+    pub struct Bar;
+}
+```
+
+Now we'll have a `Reexports` line, and `Bar` will not link to anywhere.
 
 ## `#[doc(hidden)]`