Auto merge of #42414 - frewsxcv:frewsxcv/improve-cow-docs, r=QuietMis…

…dreavus

Improve `Cow` method doc examples.

None

src/libcollections/borrow.rs

@@ -191,13 +191,16 @@ impl<'a, B: ?Sized> Cow<'a, B>
     /// # Examples
     ///
     /// ```
+    /// use std::ascii::AsciiExt;
     /// use std::borrow::Cow;
     ///
-    /// let mut cow: Cow<[_]> = Cow::Owned(vec![1, 2, 3]);
+    /// let mut cow = Cow::Borrowed("foo");
+    /// cow.to_mut().make_ascii_uppercase();
     ///
-    /// let hello = cow.to_mut();
-    ///
-    /// assert_eq!(hello, &[1, 2, 3]);
+    /// assert_eq!(
+    ///   cow,
+    ///   Cow::Owned(String::from("FOO")) as Cow<str>
+    /// );
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn to_mut(&mut self) -> &mut <B as ToOwned>::Owned {
@@ -219,14 +222,33 @@ impl<'a, B: ?Sized> Cow<'a, B>
     ///
     /// # Examples
     ///
+    /// Calling `into_owned` on a `Cow::Borrowed` clones the underlying data
+    /// and becomes a `Cow::Owned`:
+    ///
     /// ```
     /// use std::borrow::Cow;
     ///
-    /// let cow: Cow<[_]> = Cow::Owned(vec![1, 2, 3]);
+    /// let s = "Hello world!";
+    /// let cow = Cow::Borrowed(s);
+    ///
+    /// assert_eq!(
+    ///   cow.into_owned(),
+    ///   Cow::Owned(String::from(s))
+    /// );
+    /// ```
+    ///
+    /// Calling `into_owned` on a `Cow::Owned` is a no-op:
+    ///
+    /// ```
+    /// use std::borrow::Cow;
     ///
-    /// let hello = cow.into_owned();
+    /// let s = "Hello world!";
+    /// let cow: Cow<str> = Cow::Owned(String::from(s));
     ///
-    /// assert_eq!(vec![1, 2, 3], hello);
+    /// assert_eq!(
+    ///   cow.into_owned(),
+    ///   Cow::Owned(String::from(s))
+    /// );
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn into_owned(self) -> <B as ToOwned>::Owned {