Rollup merge of #38636 - shahn:extend, r=steveklabnik

Clarify Extend behaviour wrt existing keys

This seems to be consistent with all the Extend implementations I found, and isn't documented anywhere else afaik.

1 files changed, 4 insertions, 1 deletions

diff --git a/src/libcore/iter/traits.rs b/src/libcore/iter/traits.rs
index 25406696620..1e127148300 100644
--- a/src/libcore/iter/traits.rs
+++ b/src/libcore/iter/traits.rs
@@ -260,7 +260,10 @@ impl<I: Iterator> IntoIterator for I {
 ///
 /// Iterators produce a series of values, and collections can also be thought
 /// of as a series of values. The `Extend` trait bridges this gap, allowing you
-/// to extend a collection by including the contents of that iterator.
+/// to extend a collection by including the contents of that iterator. When
+/// extending a collection with an already existing key, that entry is updated
+/// or, in the case of collections that permit multiple entries with equal
+/// keys, that entry is inserted.
 ///
 /// # Examples
 ///