Skip to content

Commit f2cc1d4

Browse files
GH Actions RunnerGH Actions Runner
GH Actions Runner
authored and
GH Actions Runner
committed
publish: Merge pull request #16 from rust-lang/fix/must-use
generated from commit e5beed3
1 parent 185c215 commit f2cc1d4

File tree

2 files changed

+16
-48
lines changed

2 files changed

+16
-48
lines changed

‎code-considerations/design/must-use.html

Lines changed: 8 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -170,39 +170,23 @@ <h1 class="menu-title">Standard library developers Guide</h1>
170170
<h1><a class="header" href="#when-to-add-must_use" id="when-to-add-must_use">When to add <code>#[must_use]</code></a></h1>
171171
<p>The <code>#[must_use]</code> attribute can be applied to types or functions when failing to explicitly consider them or their output is almost certainly a bug.</p>
172172
<p>As an example, <code>Result</code> is <code>#[must_use]</code> because failing to consider it may indicate a caller didn't realise a method was fallible:</p>
173-
<pre><pre class="playground"><code class="language-rust edition2018">
174-
<span class="boring">#![allow(unused)]
175-
</span><span class="boring">fn main() {
176-
</span>// Is `check_status` infallible? Or did we forget to look at its `Result`?
173+
<pre><code class="language-rust ignore">// Is `check_status` infallible? Or did we forget to look at its `Result`?
177174
check_status();
178-
<span class="boring">}
179-
</span></code></pre></pre>
175+
</code></pre>
180176
<p>Operators like <code>saturating_add</code> are also <code>#[must_use]</code> because failing to consider their output might indicate a caller didn't realise they don't mutate the left-hand-side:</p>
181-
<pre><pre class="playground"><code class="language-rust edition2018">
182-
<span class="boring">#![allow(unused)]
183-
</span><span class="boring">fn main() {
184-
</span>// A caller might assume this method mutates `a`
177+
<pre><code class="language-rust ignore">// A caller might assume this method mutates `a`
185178
a.saturating_add(b);
186-
<span class="boring">}
187-
</span></code></pre></pre>
179+
</code></pre>
188180
<p>Combinators produced by the <code>Iterator</code> trait are <code>#[must_use]</code> because failing to use them might indicate a caller didn't realize <code>Iterator</code>s are lazy and won't actually do anything unless you drive them:</p>
189-
<pre><pre class="playground"><code class="language-rust edition2018">
190-
<span class="boring">#![allow(unused)]
191-
</span><span class="boring">fn main() {
192-
</span>// A caller might not realise this code won't do anything
181+
<pre><code class="language-rust ignore">// A caller might not realise this code won't do anything
193182
// unless they call `collect`, `count`, etc.
194183
v.iter().map(|x| println!(&quot;{}&quot;, x));
195-
<span class="boring">}
196-
</span></code></pre></pre>
184+
</code></pre>
197185
<p>On the other hand, <code>thread::JoinHandle</code> isn't <code>#[must_use]</code> 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:</p>
198-
<pre><pre class="playground"><code class="language-rust edition2018">
199-
<span class="boring">#![allow(unused)]
200-
</span><span class="boring">fn main() {
201-
</span>thread::spawn(|| {
186+
<pre><code class="language-rust ignore">thread::spawn(|| {
202187
// this background work isn't waited on
203188
});
204-
<span class="boring">}
205-
</span></code></pre></pre>
189+
</code></pre>
206190
<h2><a class="header" href="#for-reviewers" id="for-reviewers">For reviewers</a></h2>
207191
<p>Look for any legitimate use-cases where <code>#[must_use]</code> will cause callers to explicitly ignore values. If these are common then <code>#[must_use]</code> probably isn't appropriate.</p>
208192
<p>The <code>#[must_use]</code> attribute only produces warnings, so it can technically be introduced at any time. To avoid accumulating nuisance warnings though ping <code>@rust-lang/libs</code> for input before adding new <code>#[must_use]</code> attributes to existing types and functions.</p>

‎print.html

Lines changed: 8 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -309,39 +309,23 @@ <h2><a class="header" href="#for-reviewers-1" id="for-reviewers-1">For reviewers
309309
<h1><a class="header" href="#when-to-add-must_use" id="when-to-add-must_use">When to add <code>#[must_use]</code></a></h1>
310310
<p>The <code>#[must_use]</code> attribute can be applied to types or functions when failing to explicitly consider them or their output is almost certainly a bug.</p>
311311
<p>As an example, <code>Result</code> is <code>#[must_use]</code> because failing to consider it may indicate a caller didn't realise a method was fallible:</p>
312-
<pre><pre class="playground"><code class="language-rust edition2018">
313-
<span class="boring">#![allow(unused)]
314-
</span><span class="boring">fn main() {
315-
</span>// Is `check_status` infallible? Or did we forget to look at its `Result`?
312+
<pre><code class="language-rust ignore">// Is `check_status` infallible? Or did we forget to look at its `Result`?
316313
check_status();
317-
<span class="boring">}
318-
</span></code></pre></pre>
314+
</code></pre>
319315
<p>Operators like <code>saturating_add</code> are also <code>#[must_use]</code> because failing to consider their output might indicate a caller didn't realise they don't mutate the left-hand-side:</p>
320-
<pre><pre class="playground"><code class="language-rust edition2018">
321-
<span class="boring">#![allow(unused)]
322-
</span><span class="boring">fn main() {
323-
</span>// A caller might assume this method mutates `a`
316+
<pre><code class="language-rust ignore">// A caller might assume this method mutates `a`
324317
a.saturating_add(b);
325-
<span class="boring">}
326-
</span></code></pre></pre>
318+
</code></pre>
327319
<p>Combinators produced by the <code>Iterator</code> trait are <code>#[must_use]</code> because failing to use them might indicate a caller didn't realize <code>Iterator</code>s are lazy and won't actually do anything unless you drive them:</p>
328-
<pre><pre class="playground"><code class="language-rust edition2018">
329-
<span class="boring">#![allow(unused)]
330-
</span><span class="boring">fn main() {
331-
</span>// A caller might not realise this code won't do anything
320+
<pre><code class="language-rust ignore">// A caller might not realise this code won't do anything
332321
// unless they call `collect`, `count`, etc.
333322
v.iter().map(|x| println!(&quot;{}&quot;, x));
334-
<span class="boring">}
335-
</span></code></pre></pre>
323+
</code></pre>
336324
<p>On the other hand, <code>thread::JoinHandle</code> isn't <code>#[must_use]</code> 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:</p>
337-
<pre><pre class="playground"><code class="language-rust edition2018">
338-
<span class="boring">#![allow(unused)]
339-
</span><span class="boring">fn main() {
340-
</span>thread::spawn(|| {
325+
<pre><code class="language-rust ignore">thread::spawn(|| {
341326
// this background work isn't waited on
342327
});
343-
<span class="boring">}
344-
</span></code></pre></pre>
328+
</code></pre>
345329
<h2><a class="header" href="#for-reviewers-2" id="for-reviewers-2">For reviewers</a></h2>
346330
<p>Look for any legitimate use-cases where <code>#[must_use]</code> will cause callers to explicitly ignore values. If these are common then <code>#[must_use]</code> probably isn't appropriate.</p>
347331
<p>The <code>#[must_use]</code> attribute only produces warnings, so it can technically be introduced at any time. To avoid accumulating nuisance warnings though ping <code>@rust-lang/libs</code> for input before adding new <code>#[must_use]</code> attributes to existing types and functions.</p>

0 commit comments

Comments
 (0)