From 69a37a63fa1d20286ffb7c6e74060634bc8ad5a4 Mon Sep 17 00:00:00 2001
From: Michael Howell <michael@notriddle.com>
Date: Tue, 2 Mar 2021 16:37:50 -0700
Subject: [PATCH] Add documentation for string->Cow conversions

Mostly, it's just to reassure everyone that these functions don't allocate.

Part of #51430
---
 library/alloc/src/string.rs | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/library/alloc/src/string.rs b/library/alloc/src/string.rs
index b567d0a2fe2..e2e705d7980 100644
--- a/library/alloc/src/string.rs
+++ b/library/alloc/src/string.rs
@@ -2352,6 +2352,16 @@ fn from(s: Cow<'a, str>) -> String {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<'a> From<&'a str> for Cow<'a, str> {
+    /// Converts a string slice into a Borrowed variant.
+    /// No heap allocation is performed, and the string
+    /// is not copied.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use std::borrow::Cow;
+    /// assert_eq!(Cow::from("eggplant"), Cow::Borrowed("eggplant"));
+    /// ```
     #[inline]
     fn from(s: &'a str) -> Cow<'a, str> {
         Cow::Borrowed(s)
@@ -2360,6 +2370,18 @@ fn from(s: &'a str) -> Cow<'a, str> {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<'a> From<String> for Cow<'a, str> {
+    /// Converts a String into an Owned variant.
+    /// No heap allocation is performed, and the string
+    /// is not copied.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use std::borrow::Cow;
+    /// let s = "eggplant".to_string();
+    /// let s2 = "eggplant".to_string();
+    /// assert_eq!(Cow::from(s), Cow::<'static, str>::Owned(s2));
+    /// ```
     #[inline]
     fn from(s: String) -> Cow<'a, str> {
         Cow::Owned(s)
@@ -2368,6 +2390,17 @@ fn from(s: String) -> Cow<'a, str> {
 
 #[stable(feature = "cow_from_string_ref", since = "1.28.0")]
 impl<'a> From<&'a String> for Cow<'a, str> {
+    /// Converts a String reference into a Borrowed variant.
+    /// No heap allocation is performed, and the string
+    /// is not copied.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use std::borrow::Cow;
+    /// let s = "eggplant".to_string();
+    /// assert_eq!(Cow::from(&s), Cow::Borrowed("eggplant"));
+    /// ```
     #[inline]
     fn from(s: &'a String) -> Cow<'a, str> {
         Cow::Borrowed(s.as_str())