Rollup merge of #94022 - jongiddy:cow-into-owned-docs, r=Dylan-DPC

Clarify that `Cow::into_owned` returns owned data

Two sections of the `Cow::into_owned` docs imply that `into_owned` returns a `Cow`. Clarify that it returns the underlying owned object, either cloned or extracted from the `Cow`.

diff --git a/library/alloc/src/borrow.rs b/library/alloc/src/borrow.rs
index 8b13e36c4b3c7e342a45d403b0ef901f3dd80c0c..cb4e438f8bea22cbd34455f8aed2791f2bc5e856 100644 (file)
--- a/library/alloc/src/borrow.rs
+++ b/library/alloc/src/borrow.rs
@@ -292,8 +292,7 @@ pub fn to_mut(&mut self) -> &mut <B as ToOwned>::Owned {
     ///
     /// # Examples
     ///
-    /// Calling `into_owned` on a `Cow::Borrowed` clones the underlying data
-    /// and becomes a `Cow::Owned`:
+    /// Calling `into_owned` on a `Cow::Borrowed` returns a clone of the borrowed data:
     ///
     /// ```
     /// use std::borrow::Cow;
@@ -307,7 +306,8 @@ pub fn to_mut(&mut self) -> &mut <B as ToOwned>::Owned {
     /// );
     /// ```
     ///
-    /// Calling `into_owned` on a `Cow::Owned` is a no-op:
+    /// Calling `into_owned` on a `Cow::Owned` returns the owned data. The data is moved out of the
+    /// `Cow` without being cloned.
     ///
     /// ```
     /// use std::borrow::Cow;