For Extend, document collections allowing duplicate keys

Author: shahn

src/libcore/iter/traits.rs

@@ -261,7 +261,9 @@ 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. When
-/// extending a collection with an already existing key, that entry is updated.
+/// 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
 ///