auto merge of #14391 : alexcrichton/rust/more-rustdoc-inline, r=huonw

As part of the libstd facade (cc #13851), rustdoc is taught to inline documentation across crate boundaries through the usage of a `pub use` statement. This is done to allow libstd to maintain the facade that it is a standalone library with a defined public interface (allowing us to shuffle around what's underneath it).

A preview is available at http://people.mozilla.org/~acrichton/doc/std/index.html

src/doc/rustdoc.md

@@ -41,6 +41,31 @@ pub fn recalibrate() {
 # }
 ~~~
 
+Documentation can also be controlled via the `doc` attribute on items. This is
+implicitly done by the compiler when using the above form of doc comments
+(converting the slash-based comments to `#[doc]` attributes).
+
+~~~
+#[doc = "
+Calculates the factorial of a number.
+
+Given the input integer `n`, this function will calculate `n!` and return it.
+"]
+pub fn factorial(n: int) -> int { if n < 2 {1} else {n * factorial(n)} }
+# fn main() {}
+~~~
+
+The `doc` attribute can also be used to control how rustdoc emits documentation
+in some cases.
+
+```
+// Rustdoc will inline documentation of a `pub use` into this crate when the
+// `pub use` reaches across crates, but this behavior can also be disabled.
+#[doc(no_inline)]
+pub use std::option::Option;
+# fn main() {}
+```
+
 Doc comments are markdown, and are currently parsed with the
 [sundown][sundown] library. rustdoc does not yet do any fanciness such as
 referencing other items inline, like javadoc's `@see`. One exception to this