Update docs for str::as_bytes_mut.

* Add "Safety" section describing UTF-8 invariant.

* Remove mention of `from_utf8_mut`.  It is not necessary to call
  a function to convert the byte slice back to a string slice.  The
  original string becomes accessible again after the byte slice is
  no longer used (as shown in the example code).

diff --git a/src/libcore/str/mod.rs b/src/libcore/str/mod.rs
index 0014501d2c4d0624958317bcde37ecd587454180..10721ce6165d6d52e52a03f407cb22849469fb92 100644 (file)
--- a/src/libcore/str/mod.rs
+++ b/src/libcore/str/mod.rs
@@ -2384,11 +2384,14 @@ union Slices<'a> {
         unsafe { Slices { str: self }.slice }
     }
 
-    /// Converts a mutable string slice to a mutable byte slice. To convert the
-    /// mutable byte slice back into a mutable string slice, use the
-    /// [`str::from_utf8_mut`] function.
+    /// Converts a mutable string slice to a mutable byte slice.
     ///
-    /// [`str::from_utf8_mut`]: ./str/fn.from_utf8_mut.html
+    /// # Safety
+    ///
+    /// The caller must ensure that the content of the slice is valid UTF-8
+    /// before the borrow ends and the underlying `str` is used.
+    ///
+    /// Use of a `str` whose contents are not valid UTF-8 is undefined behavior.
     ///
     /// # Examples
     ///