Document that BTreeMap iteration is in order

Also change the examples to make this more obvious. Fixes #31129.

src/libcollections/btree/map.rs

@@ -1194,17 +1194,17 @@ unsafe fn unwrap_unchecked<T>(val: Option<T>) -> T {
 }
 
 impl<K, V> BTreeMap<K, V> {
-    /// Gets an iterator over the entries of the map.
+    /// Gets an iterator over the entries of the map, sorted by key.
     ///
     /// # Examples
     ///
     /// ```
     /// use std::collections::BTreeMap;
     ///
     /// let mut map = BTreeMap::new();
-    /// map.insert(1, "a");
-    /// map.insert(2, "b");
     /// map.insert(3, "c");
+    /// map.insert(2, "b");
+    /// map.insert(1, "a");
     ///
     /// for (key, value) in map.iter() {
     ///     println!("{}: {}", key, value);
@@ -1224,7 +1224,7 @@ impl<K, V> BTreeMap<K, V> {
         }
     }
 
-    /// Gets a mutable iterator over the entries of the map.
+    /// Gets a mutable iterator over the entries of the map, sorted by key.
     ///
     /// # Examples
     ///
@@ -1257,16 +1257,16 @@ impl<K, V> BTreeMap<K, V> {
         }
     }
 
-    /// Gets an iterator over the keys of the map.
+    /// Gets an iterator over the keys of the map, in sorted order.
     ///
     /// # Examples
     ///
     /// ```
     /// use std::collections::BTreeMap;
     ///
     /// let mut a = BTreeMap::new();
-    /// a.insert(1, "a");
     /// a.insert(2, "b");
+    /// a.insert(1, "a");
     ///
     /// let keys: Vec<_> = a.keys().cloned().collect();
     /// assert_eq!(keys, [1, 2]);
@@ -1276,19 +1276,19 @@ impl<K, V> BTreeMap<K, V> {
         Keys { inner: self.iter() }
     }
 
-    /// Gets an iterator over the values of the map.
+    /// Gets an iterator over the values of the map, in order by key.
     ///
     /// # Examples
     ///
     /// ```
     /// use std::collections::BTreeMap;
     ///
     /// let mut a = BTreeMap::new();
-    /// a.insert(1, "a");
-    /// a.insert(2, "b");
+    /// a.insert(1, "hello");
+    /// a.insert(2, "goodbye");
     ///
     /// let values: Vec<&str> = a.values().cloned().collect();
-    /// assert_eq!(values, ["a", "b"]);
+    /// assert_eq!(values, ["hello", "goodbye"]);
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn values<'a>(&'a self) -> Values<'a, K, V> {