Skip to content

Fix build failure from must_use docs #16

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
Feb 9, 2021
Merged
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
8 changes: 4 additions & 4 deletions src/code-considerations/design/must-use.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,29 +4,29 @@ The `#[must_use]` attribute can be applied to types or functions when failing to

As an example, `Result` is `#[must_use]` because failing to consider it may indicate a caller didn't realise a method was fallible:

```rust
```rust,ignore
// Is `check_status` infallible? Or did we forget to look at its `Result`?
check_status();
```

Operators like `saturating_add` are also `#[must_use]` because failing to consider their output might indicate a caller didn't realise they don't mutate the left-hand-side:

```rust
```rust,ignore
// A caller might assume this method mutates `a`
a.saturating_add(b);
```

Combinators produced by the `Iterator` trait are `#[must_use]` because failing to use them might indicate a caller didn't realize `Iterator`s are lazy and won't actually do anything unless you drive them:

```rust
```rust,ignore
// A caller might not realise this code won't do anything
// unless they call `collect`, `count`, etc.
v.iter().map(|x| println!("{}", x));
```

On the other hand, `thread::JoinHandle` isn't `#[must_use]` because spawning fire-and-forget work is a legitimate pattern and forcing callers to explicitly ignore handles could be a nuisance rather than an indication of a bug:

```rust
```rust,ignore
thread::spawn(|| {
// this background work isn't waited on
});
Expand Down