Indicate that `BTreeSet::iter` returns values in ascending order.

Fixes https://github.com/rust-lang/rust/issues/38204.

diff --git a/src/libcollections/btree/set.rs b/src/libcollections/btree/set.rs
index ffd5d7a91927154feeed9cda99026737b4d72e0d..34674e3a0bd3098da987525b68812ba805970817 100644 (file)
--- a/src/libcollections/btree/set.rs
+++ b/src/libcollections/btree/set.rs
@@ -173,7 +173,7 @@ pub fn new() -> BTreeSet<T> {
 }
 
 impl<T> BTreeSet<T> {
-    /// Gets an iterator over the `BTreeSet`'s contents.
+    /// Gets an iterator that visits the values in the `BTreeSet` in ascending order.
     ///
     /// # Examples
     ///
@@ -187,6 +187,19 @@ impl<T> BTreeSet<T> {
     /// assert_eq!(set_iter.next(), Some(&3));
     /// assert_eq!(set_iter.next(), None);
     /// ```
+    ///
+    /// Values returned by the iterator are returned in ascending order:
+    ///
+    /// ```
+    /// use std::collections::BTreeSet;
+    ///
+    /// let set: BTreeSet<usize> = [3, 1, 2].iter().cloned().collect();
+    /// let mut set_iter = set.iter();
+    /// assert_eq!(set_iter.next(), Some(&1));
+    /// assert_eq!(set_iter.next(), Some(&2));
+    /// assert_eq!(set_iter.next(), Some(&3));
+    /// assert_eq!(set_iter.next(), None);
+    /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn iter(&self) -> Iter<T> {
         Iter { iter: self.map.keys() }