Skip to content

Commit

Permalink
Merge pull request #1740 from kberov/meta_doc
Browse files Browse the repository at this point in the history
Wrapped long lines and put #[doc] in backquotes.
  • Loading branch information
marioidival committed Sep 26, 2023
2 parents e314c6c + 257c339 commit f61675f
Show file tree
Hide file tree
Showing 2 changed files with 17 additions and 7 deletions.
9 changes: 6 additions & 3 deletions src/meta/doc.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@

Use `cargo doc` to build documentation in `target/doc`.

Use `cargo test` to run all tests (including documentation tests), and `cargo test --doc` to only run documentation tests.
Use `cargo test` to run all tests (including documentation tests), and `cargo
test --doc` to only run documentation tests.

These commands will appropriately invoke `rustdoc` (and `rustc`) as required.

Expand Down Expand Up @@ -67,7 +68,8 @@ $ rustdoc --test --extern doc="libdoc.rlib" doc.rs

## Doc attributes

Below are a few examples of the most common `#[doc]` attributes used with `rustdoc`.
Below are a few examples of the most common `#[doc]` attributes used with
`rustdoc`.

### `inline`

Expand Down Expand Up @@ -104,7 +106,8 @@ Using this tells `rustdoc` not to include this in documentation:
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/).
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:

Expand Down
15 changes: 11 additions & 4 deletions src/meta/playground.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# Playground

The [Rust Playground](https://play.rust-lang.org/) is a way to experiment with Rust code through a web interface.
The [Rust Playground](https://play.rust-lang.org/) is a way to experiment with
Rust code through a web interface.

## Using it with `mdbook`

Expand All @@ -12,15 +13,18 @@ fn main() {
}
```

This allows the reader to both run your code sample, but also modify and tweak it. The key here is the adding the word `editable` to your codefence block separated by a comma.
This allows the reader to both run your code sample, but also modify and tweak
it. The key here is the adding the word `editable` to your codefence block
separated by a comma.

````markdown
```rust,editable
//...place your code here
```
````

Additionally, you can add `ignore` if you want `mdbook` to skip your code when it builds and tests.
Additionally, you can add `ignore` if you want `mdbook` to skip your code when
it builds and tests.

````markdown
```rust,editable,ignore
Expand All @@ -30,7 +34,10 @@ Additionally, you can add `ignore` if you want `mdbook` to skip your code when i

## 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].
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].

### See also:

Expand Down

0 comments on commit f61675f

Please sign in to comment.