From 4854e37dbce901db40cc94f078cce87985d7e0b1 Mon Sep 17 00:00:00 2001
From: philipp <descpl@yahoo.de>
Date: Sat, 15 Oct 2022 14:59:27 +0200
Subject: [PATCH] Documentation BTreeMap::append's behavior for already
 existing keys

---
 library/alloc/src/collections/btree/map.rs | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/library/alloc/src/collections/btree/map.rs b/library/alloc/src/collections/btree/map.rs
index 73bc1c21d55..c4c75e46a2a 100644
--- a/library/alloc/src/collections/btree/map.rs
+++ b/library/alloc/src/collections/btree/map.rs
@@ -1093,6 +1093,9 @@ pub fn retain<F>(&mut self, mut f: F)
 
     /// Moves all elements from `other` into `self`, leaving `other` empty.
     ///
+    /// If a key from `other` is already present in `self`, the respective
+    /// value from `self` will be overwritten with the respective value from `other`.
+    ///
     /// # Examples
     ///
     /// ```
@@ -1101,10 +1104,10 @@ pub fn retain<F>(&mut self, mut f: F)
     /// let mut a = BTreeMap::new();
     /// a.insert(1, "a");
     /// a.insert(2, "b");
-    /// a.insert(3, "c");
+    /// a.insert(3, "c"); // Note: Key (3) also present in b.
     ///
     /// let mut b = BTreeMap::new();
-    /// b.insert(3, "d");
+    /// b.insert(3, "d"); // Note: Key (3) also present in a.
     /// b.insert(4, "e");
     /// b.insert(5, "f");
     ///
@@ -1115,7 +1118,7 @@ pub fn retain<F>(&mut self, mut f: F)
     ///
     /// assert_eq!(a[&1], "a");
     /// assert_eq!(a[&2], "b");
-    /// assert_eq!(a[&3], "d");
+    /// assert_eq!(a[&3], "d"); // Note: "c" has been overwritten.
     /// assert_eq!(a[&4], "e");
     /// assert_eq!(a[&5], "f");
     /// ```