Auto merge of #44620 - zackmdavis:rfc_1940_housekeeping, r=nikomatsakis

RFC 1940 housekeeping

* move test to own directory, as requested in #43302 (comment)
* exercise trait methods in test
* unstable book section

r? @nikomatsakis

src/doc/unstable-book/src/language-features/fn-must-use.md

@@ -0,0 +1,30 @@
+# `fn_must_use`
+
+The tracking issue for this feature is [#43302].
+
+[#43302]: https://github.com/rust-lang/rust/issues/43302
+
+------------------------
+
+The `fn_must_use` feature allows functions and methods to be annotated with
+`#[must_use]`, indicating that the `unused_must_use` lint should require their
+return values to be used (similarly to how types annotated with `must_use`,
+most notably `Result`, are linted if not used).
+
+## Examples
+
+```rust
+#![feature(fn_must_use)]
+
+#[must_use]
+fn double(x: i32) -> i32 {
+    2 * x
+}
+
+fn main() {
+    double(4); // warning: unused return value of `double` which must be used
+
+    let _ = double(4); // (no warning)
+}
+
+```

src/test/ui/rfc_1940-must_use_on_functions/fn_must_use.rs

@@ -0,0 +1,70 @@
+// Copyright 2017 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+#![feature(fn_must_use)]
+#![warn(unused_must_use)]
+
+struct MyStruct {
+    n: usize,
+}
+
+impl MyStruct {
+    #[must_use]
+    fn need_to_use_this_method_value(&self) -> usize {
+        self.n
+    }
+}
+
+trait EvenNature {
+    #[must_use = "no side effects"]
+    fn is_even(&self) -> bool;
+}
+
+impl EvenNature for MyStruct {
+    fn is_even(&self) -> bool {
+        self.n % 2 == 0
+    }
+}
+
+trait Replaceable {
+    fn replace(&mut self, substitute: usize) -> usize;
+}
+
+impl Replaceable for MyStruct {
+    // ↓ N.b.: `#[must_use]` attribute on a particular trait implementation
+    // method won't work; the attribute should be on the method signature in
+    // the trait's definition.
+    #[must_use]
+    fn replace(&mut self, substitute: usize) -> usize {
+        let previously = self.n;
+        self.n = substitute;
+        previously
+    }
+}
+
+#[must_use = "it's important"]
+fn need_to_use_this_value() -> bool {
+    false
+}
+
+fn main() {
+    need_to_use_this_value();
+
+    let mut m = MyStruct { n: 2 };
+    m.need_to_use_this_method_value();
+    m.is_even(); // trait method!
+
+    m.replace(3);
+
+    2.eq(&3);
+
+    // FIXME: operators should probably be `must_use` if underlying method is
+    2 == 3;
+}

src/test/ui/rfc_1940-must_use_on_functions/fn_must_use.stderr

@@ -0,0 +1,30 @@
+warning: unused return value of `need_to_use_this_value` which must be used: it's important
+  --> $DIR/fn_must_use.rs:58:5
+   |
+58 |     need_to_use_this_value();
+   |     ^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+note: lint level defined here
+  --> $DIR/fn_must_use.rs:12:9
+   |
+12 | #![warn(unused_must_use)]
+   |         ^^^^^^^^^^^^^^^
+
+warning: unused return value of `MyStruct::need_to_use_this_method_value` which must be used
+  --> $DIR/fn_must_use.rs:61:5
+   |
+61 |     m.need_to_use_this_method_value();
+   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+warning: unused return value of `EvenNature::is_even` which must be used: no side effects
+  --> $DIR/fn_must_use.rs:62:5
+   |
+62 |     m.is_even(); // trait method!
+   |     ^^^^^^^^^^^^
+
+warning: unused return value of `std::cmp::PartialEq::eq` which must be used
+  --> $DIR/fn_must_use.rs:66:5
+   |
+66 |     2.eq(&3);
+   |     ^^^^^^^^^
+