Merge pull request #1323 from jsjoeio/jsjoeio/108-doc-attribute-examples

feat: add doc attributes section to documentation

src/meta/doc.md

@@ -6,13 +6,13 @@ Use `cargo test` to run all tests (including documentation tests), and `cargo te
 
 These commands will appropriately invoke `rustdoc` (and `rustc`) as required.
 
-### Doc comments
+## Doc comments
 
 Doc comments are very useful for big projects that require documentation. When
 running `rustdoc`, these are the comments that get compiled into
 documentation. They are denoted by a `///`, and support [Markdown].
 
-```rust,editable,ignore
+````rust,editable,ignore
 #![crate_name = "doc"]
 
 /// A human being is represented here
@@ -55,7 +55,7 @@ fn main() {
 
     john.hello();
 }
-```
+````
 
 To run the tests, first build the code as a library, then tell `rustdoc` where
 to find the library so it can link it into each doctest program:
@@ -65,18 +65,57 @@ $ rustc doc.rs --crate-type lib
 $ rustdoc --test --extern doc="libdoc.rlib" doc.rs
 ```
 
+## Doc attributes
+
+Below are a few examples of the most common `#[doc]` attributes used with `rustdoc`.
+
+### `inline`
+
+Used to inline docs, instead of linking out to separate page.
+
+```rust,ignore
+#[doc(inline)]
+pub use bar::Bar;
+
+/// bar docs
+mod bar {
+    /// the docs for Bar
+    pub struct Bar;
+}
+```
+
+### `no_inline`
+
+Used to prevent linking out to separate page or anywhere.
+
+```rust,ignore
+// Example from libcore/prelude
+#[doc(no_inline)]
+pub use crate::mem::drop;
+```
+
+### `hidden`
+
+Using this tells `rustdoc` not to include this in documentation:
+
+```rust,editable,ignore
+// Example from the futures-rs library
+#[doc(hidden)]
+pub use self::async_await::*;
+```
+
 For documentation, `rustdoc` is widely used by the community. It's what is used to generate the [std library docs](https://doc.rust-lang.org/std/).
 
 ### See also:
 
-* [The Rust Book: Making Useful Documentation Comments][book]
-* [The rustdoc Book][rustdoc-book]
-* [The Reference: Doc comments][ref-comments]
-* [RFC 1574: API Documentation Conventions][api-conv]
-* [RFC 1946: Relative links to other items from doc comments (intra-rustdoc links)][intra-links]
-* [Is there any documentation style guide for comments? (reddit)][reddit]
+- [The Rust Book: Making Useful Documentation Comments][book]
+- [The rustdoc Book][rustdoc-book]
+- [The Reference: Doc comments][ref-comments]
+- [RFC 1574: API Documentation Conventions][api-conv]
+- [RFC 1946: Relative links to other items from doc comments (intra-rustdoc links)][intra-links]
+- [Is there any documentation style guide for comments? (reddit)][reddit]
 
-[Markdown]: https://en.wikipedia.org/wiki/Markdown
+[markdown]: https://en.wikipedia.org/wiki/Markdown
 [book]: https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html#making-useful-documentation-comments
 [ref-comments]: https://doc.rust-lang.org/stable/reference/comments.html#doc-comments
 [rustdoc-book]: https://doc.rust-lang.org/rustdoc/index.html

src/meta/playpen.md

@@ -20,6 +20,14 @@ This allows the reader to both run your code sample, but also modify and tweak i
 ```
 ````
 
+Additionally, you can add `ignore` if you want `mdbook` to skip your code when it builds and tests.
+
+````markdown
+```rust,editable,ignore
+//...place your code here
+```
+````
+
 ## Using it with docs
 
 You may have noticed in some of the [official Rust docs][official-rust-docs] a button that says "Run", which opens the code sample up in a new tab in Rust Playground. This feature is enabled if you use the #[doc] attribute called [`html_playground_url`][html-playground-url].