From 6a0cdb0ef7f964594eec1d99bef5f172751499a5 Mon Sep 17 00:00:00 2001 From: Joe Previte Date: Wed, 25 Mar 2020 14:50:26 -0700 Subject: [PATCH 1/5] feat: add doc attributes section to documentation --- src/meta/doc.md | 39 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/src/meta/doc.md b/src/meta/doc.md index 4aa2cbf0cc..444b00e07e 100644 --- a/src/meta/doc.md +++ b/src/meta/doc.md @@ -6,7 +6,7 @@ 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 @@ -65,6 +65,43 @@ $ 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 +#[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] From 94ca1f7d667c8f67f8bc4743322347f83a534c2f Mon Sep 17 00:00:00 2001 From: Joe Previte Date: Wed, 25 Mar 2020 14:53:46 -0700 Subject: [PATCH 2/5] Update src/meta/doc.md --- src/meta/doc.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/meta/doc.md b/src/meta/doc.md index 444b00e07e..7ca6458c29 100644 --- a/src/meta/doc.md +++ b/src/meta/doc.md @@ -85,6 +85,7 @@ mod bar { ``` ### `no_inline` + Used to prevent linking out to separate page or anywhere. ```rust From 4324f2e5c8ee5873ab2b10dfb265b881a6026a35 Mon Sep 17 00:00:00 2001 From: Joe Previte Date: Wed, 25 Mar 2020 14:50:26 -0700 Subject: [PATCH 3/5] feat: add doc attributes section to documentation --- src/meta/doc.md | 59 ++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 48 insertions(+), 11 deletions(-) diff --git a/src/meta/doc.md b/src/meta/doc.md index cd60abb21c..f4051799db 100644 --- a/src/meta/doc.md +++ b/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 From 051382af6e603cac434b72780a0c0c9b76d2aa5b Mon Sep 17 00:00:00 2001 From: Joe Previte Date: Sun, 29 Mar 2020 15:04:26 -0700 Subject: [PATCH 4/5] fix: ignore code examples in doc --- src/meta/doc.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/meta/doc.md b/src/meta/doc.md index c51a767499..da6ff9ea8c 100644 --- a/src/meta/doc.md +++ b/src/meta/doc.md @@ -73,7 +73,7 @@ Below are a few examples of the most common `#[doc]` attributes used with `rustd Used to inline docs, instead of linking out to separate page. -```rust +```rust,ignore #[doc(inline)] pub use bar::Bar; @@ -88,7 +88,7 @@ mod bar { Used to prevent linking out to separate page or anywhere. -```rust +```rust,ignore // Example from libcore/prelude #[doc(no_inline)] pub use crate::mem::drop; @@ -98,7 +98,7 @@ pub use crate::mem::drop; Using this tells `rustdoc` not to include this in documentation: -```rust,editable +```rust,editable,ignore // Example from the futures-rs library #[doc(hidden)] pub use self::async_await::*; From 5382d4b7bbaa4e48b922c94e3c0848b9f44e3af1 Mon Sep 17 00:00:00 2001 From: Joe Previte Date: Sun, 29 Mar 2020 15:04:40 -0700 Subject: [PATCH 5/5] feat: add example with ignore to playpen --- src/meta/playpen.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/meta/playpen.md b/src/meta/playpen.md index e8706752cc..a125f139d8 100644 --- a/src/meta/playpen.md +++ b/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].