Clarify behavior of inclusive bounds in BTreeMap::{lower,upper}_bound

Author: zopsicle

library/alloc/src/collections/btree/map.rs

@@ -2603,6 +2603,8 @@ impl<K, V, A: Allocator + Clone> BTreeMap<K, V, A> {
     /// a.insert(2, "b");
     /// a.insert(3, "c");
     /// a.insert(4, "c");
+    /// let cursor = a.lower_bound(Bound::Included(&2));
+    /// assert_eq!(cursor.key(), Some(&2));
     /// let cursor = a.lower_bound(Bound::Excluded(&2));
     /// assert_eq!(cursor.key(), Some(&3));
     /// ```
@@ -2644,6 +2646,8 @@ impl<K, V, A: Allocator + Clone> BTreeMap<K, V, A> {
     /// a.insert(2, "b");
     /// a.insert(3, "c");
     /// a.insert(4, "c");
+    /// let cursor = a.lower_bound_mut(Bound::Included(&2));
+    /// assert_eq!(cursor.key(), Some(&2));
     /// let cursor = a.lower_bound_mut(Bound::Excluded(&2));
     /// assert_eq!(cursor.key(), Some(&3));
     /// ```
@@ -2698,6 +2702,8 @@ impl<K, V, A: Allocator + Clone> BTreeMap<K, V, A> {
     /// a.insert(2, "b");
     /// a.insert(3, "c");
     /// a.insert(4, "c");
+    /// let cursor = a.upper_bound(Bound::Included(&3));
+    /// assert_eq!(cursor.key(), Some(&3));
     /// let cursor = a.upper_bound(Bound::Excluded(&3));
     /// assert_eq!(cursor.key(), Some(&2));
     /// ```
@@ -2739,6 +2745,8 @@ impl<K, V, A: Allocator + Clone> BTreeMap<K, V, A> {
     /// a.insert(2, "b");
     /// a.insert(3, "c");
     /// a.insert(4, "c");
+    /// let cursor = a.upper_bound_mut(Bound::Included(&3));
+    /// assert_eq!(cursor.key(), Some(&3));
     /// let cursor = a.upper_bound_mut(Bound::Excluded(&3));
     /// assert_eq!(cursor.key(), Some(&2));
     /// ```