feat: add doc attributes section to documentation

Author: Joe Previte

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,55 @@ $ rustc doc.rs --crate-type lib
 $ rustdoc --test --extern doc="libdoc.rlib" doc.rs
 ```
 
-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/).
+## 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
+#[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
+// 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
+// Example from the futures-rs library
+#[doc(hidden)]
+pub use self::async_await::*;
+```
 
 ### 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