Text of rust.docs.kernel.org › src › core › attribute_docs.rs.html as Styx crawled it on Nov 20, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

attribute_docs.rs - source

Skip to main content core/ 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 /// ``` 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 /// ``` 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 /// ``` 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 /// ``` 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 /// [`unused_must_use`]: ../rustc/lints/listing/warn-by-default.html#unused-must-use 84 /// [the `must_use` attribute]: ../reference/attributes/diagnostics.html#the-must_use-attribute 85 const _ : () = (); 86 87 #[doc(attribute = "allow" )] 88 // 89 /// The `allow` attribute suppresses lint diagnostics that would otherwise produce 90 /// warnings or errors.

It can be used on any lint or lint group (except those 91 /// set to [`forbid`]). 92 /// 93 /// ``` 94 /// #[allow(dead_code)] 95 /// fn unused_function() { 96 /// // ... 97 /// } 98 /// 99 /// fn main() { 100 /// // `unused_function` does not generate a compiler warning. 101 /// } 102 /// ``` 103 /// 104 /// Without `#[allow(dead_code)]`, the example above would emit: 105 /// 106 /// ```text 107 /// warning: function `unused_function` is never used 108 /// --> main.rs:1:4 109 /// | 110 /// 1 | fn unused_function() { 111 /// | ^^^^^^^^^^^^^^^ 112 /// | 113 /// = note: `#[warn(dead_code)]` (part of `#[warn(unused)]`) on by default 114 /// 115 /// warning: 1 warning emitted 116 /// ``` 117 /// 118 /// Multiple lints can be set to `allow` at once with commas: 119 /// 120 /// ``` 121 /// #[allow(unused_variables, unused_mut)] 122 /// fn main() { 123 /// let mut x: u32 = 42; 124 /// } 125 /// ``` 126 /// 127 /// This is mostly used to prevent lint warnings or errors while still under development.

128 /// 129 /// It cannot override a lint that has been set to [`forbid`]. 130 /// 131 /// It's also important to consider that overusing `allow` could make code harder to maintain 132 /// and possibly hide issues. To mitigate this issue, using the `expect` attribute is preferred. 133 /// 134 /// `allow` can be overridden by [`warn`], [`deny`], and [`forbid`]. 135 /// 136 /// The lint checks supported by rustc can be found via `rustc -W help`, 137 /// along with their default settings and are documented in [the `rustc` book].

138 /// 139 /// [the `rustc` book]: ../rustc/lints/listing/index.html 140 /// 141 /// For more information, see the Reference on [the `allow` attribute]. 142 /// 143 /// [the `allow` attribute]: ../reference/attributes/diagnostics.html#lint-check-attributes 144 /// [`forbid`]: ./attribute.forbid.html 145 /// [`warn`]: ./attribute.warn.html 146 /// [`deny`]: ./attribute.deny.html 147 const _ : () = (); 148 149 #[doc(attribute = "cfg" )] 150 // 151 /// Used for conditional compilation.

152 /// 153 /// The `cfg` attribute allows compiling an item under specific conditions, otherwise it 154 /// will be ignored. 155 /// 156 /// ``` 157 /// // Only compiles this function for Linux. 158 /// #[cfg(target_os = "linux")] 159 /// fn platform_specific() { 160 /// println!("Running on Linux"); 161 /// } 162 /// 163 /// // Only compiles this function if not for Linux. 164 /// #[cfg(not(target_os = "linux"))] 165 /// fn platform_specific() { 166 /// println!("Running on something else"); 167 /// } 168 /// ``` 169 /// 170 /// Depending on the platform you're targeting, only one of these two functions will be considered 171 /// during the compilation.

172 /// 173 /// Conditions can also be combined with `all(...)`, `any(...)`, and `not(...)`: 174 /// 175 /// * `all`: True if all given predicates are true. 176 /// * `any`: True if at least one of the given predicates is true. 177 /// * `not`: True if the predicate is false and false if the predicate is true. 178 /// 179 /// ``` 180 /// #[cfg(all(unix, target_pointer_width = "64"))] 181 /// fn unix_64bit() { 182 /// // ...

183 /// } 184 /// ``` 185 /// 186 /// If you want to use this mechanism in an [`if`] condition in your code, you 187 /// can use the [`cfg!`] macro. To conditionally apply an attribute, 188 /// see [`cfg_attr`]. 189 /// 190 /// For more information, see the Reference on [the `cfg` attribute]. 191 /// 192 /// [`cfg_attr`]: ../reference/conditional-compilation.html#the-cfg_attr-attribute 193 /// [the `cfg` attribute]: ../reference/conditional-compilation.html#the-cfg-attribute 194 /// [`if`]: ./keyword.if.html 195 const _ : () = (); 196 197 #[doc(attribute = "deny" )] 198 // 199 /// Emits an error, preventing the compilation from finishing, when a lint check has failed.

200 /// This is useful for enforcing rules or preventing certain patterns: 201 /// 202 /// ```compile_fail 203 /// #[deny(unused)] 204 /// fn foo() { 205 /// let x = 42; // Emits an error because x is unused. 206 /// } 207 /// ``` 208 /// 209 /// `deny` can be overridden by [`allow`], [`warn`], and [`forbid`]: 210 /// 211 /// ``` 212 /// #![deny(unused)] 213 /// 214 /// #[allow(unused)] // We override the `deny` for this function.

215 /// fn foo() { 216 /// let x = 42; // No lint emitted even though `x` is unused. 217 /// } 218 /// ``` 219 /// 220 /// Multiple lints can also be set to `deny` at once: 221 /// 222 /// ```compile_fail 223 /// #![deny(unused_imports, unused_variables)] 224 /// use std::collections::

The rest of this page is on the live site.