std/attribute_docs.rs
1#[doc(attribute = "must_use")]
2//
3/// Warn when a value is ignored.
4///
5/// The `must_use` attribute applies to values where simply creating or returning them is
6/// often not enough. If a value marked with `#[must_use]` is produced and then ignored, the
7/// compiler warns through the [`unused_must_use`] lint.
8///
9/// This is most common on types that represent an important state or outcome. For example,
10/// [`Result`] is marked `#[must_use]` because ignoring an error value can hide a failed operation.
11/// In the following example, the returned `Result` is the only sign that writing the message
12/// might have failed:
13///
14/// ```rust
15/// # #![allow(unused_must_use)]
16/// fn write_message() -> std::io::Result<()> {
17/// // Write the message...
18/// Ok(())
19/// }
20///
21/// write_message();
22/// ```
23///
24/// Ignoring that `Result` triggers this warning:
25///
26/// ```text
27/// warning: unused `Result` that must be used
28/// = note: this `Result` may be an `Err` variant, which should be handled
29/// = note: `#[warn(unused_must_use)]` (part of `#[warn(unused)]`) on by default
30/// help: use `let _ = ...` to ignore the resulting value
31/// ```
32///
33/// Future values are also `#[must_use]`: creating a future does not run it, so ignoring one often
34/// means the intended asynchronous work never happens.
35///
36/// You can also place `#[must_use]` on a function, method, or trait declaration. On a function or
37/// method, the warning is tied to ignoring that call's return value:
38///
39/// ```rust
40/// # #![allow(unused_must_use)]
41/// #[must_use]
42/// fn make_token() -> String {
43/// String::from("token")
44/// }
45///
46/// // Ignoring this call's return value triggers `unused_must_use`.
47/// make_token();
48/// ```
49///
50/// On a trait, the warning applies when a function returns an opaque type (`impl Trait`) or trait
51/// object (`dyn Trait`) whose bounds include that trait. This is how futures warn if you create one
52/// but never poll or await it, since an `async fn` returns an opaque type implementing [`Future`].
53///
54/// The attribute can include a message explaining what the caller should do with the value:
55///
56/// ```rust
57/// # #![allow(dead_code)]
58/// #[must_use = "call `.finish()` to complete the operation"]
59/// fn start_operation() -> Operation {
60/// Operation
61/// }
62///
63/// struct Operation;
64/// ```
65///
66/// If intentionally ignoring the value is correct, bind it to `_` or call [`drop`]:
67///
68/// ```rust
69/// # #[must_use]
70/// # fn make_token() -> String {
71/// # String::from("token")
72/// # }
73/// let _ = make_token();
74/// drop(make_token());
75/// ```
76///
77/// The attribute is a warning tool, not a type-system rule. Code can still explicitly discard a
78/// `#[must_use]` value, and the compiler does not require callers to inspect or otherwise act on
79/// the value.
80///
81/// For more information, see the Reference on [the `must_use` attribute].
82///
83/// [`Result`]: result::Result
84/// [`Future`]: future::Future
85/// [`unused_must_use`]: ../rustc/lints/listing/warn-by-default.html#unused-must-use
86/// [the `must_use` attribute]: ../reference/attributes/diagnostics.html#the-must_use-attribute
87mod must_use_attribute {}