Skip to content

Wrapped long lines and put #[doc] in backquotes. #1740

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 26, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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