Rollup merge of #50511 - Manishearth:must-use, r=QuietMisdreavus

Add some explanations for #[must_use]

`#[must_use]` can be given a string argument which is shown whilst warning for things.

We should add a string argument to most of the user-exposed ones.

I added these for everything but the operators, mostly because I'm not sure what to write there or if we need anything there.

1 files changed, 4 insertions, 2 deletions

diff --git a/src/liballoc/str.rs b/src/liballoc/str.rs
index 0cbe65db53c..9e693c89be9 100644
--- a/src/liballoc/str.rs
+++ b/src/liballoc/str.rs
@@ -207,7 +207,8 @@ impl str {
     /// let s = "this is old";
     /// assert_eq!(s, s.replace("cookie monster", "little lamb"));
     /// ```
-    #[must_use]
+    #[must_use = "this returns the replaced string as a new allocation, \
+                  without modifying the original"]
     #[stable(feature = "rust1", since = "1.0.0")]
     #[inline]
     pub fn replace<'a, P: Pattern<'a>>(&'a self, from: P, to: &str) -> String {
@@ -247,7 +248,8 @@ impl str {
     /// let s = "this is old";
     /// assert_eq!(s, s.replacen("cookie monster", "little lamb", 10));
     /// ```
-    #[must_use]
+    #[must_use = "this returns the replaced string as a new allocation, \
+                  without modifying the original"]
     #[stable(feature = "str_replacen", since = "1.16.0")]
     pub fn replacen<'a, P: Pattern<'a>>(&'a self, pat: P, to: &str, count: usize) -> String {
         // Hope to reduce the times of re-allocation