diff --git a/src/libcore/slice/mod.rs b/src/libcore/slice/mod.rs
index 0e782bef39dd8..4838cf33d354f 100644
--- a/src/libcore/slice/mod.rs
+++ b/src/libcore/slice/mod.rs
@@ -1362,6 +1362,21 @@ impl<T> [T] {
     /// let r = s.binary_search(&1);
     /// assert!(match r { Ok(1..=4) => true, _ => false, });
     /// ```
+    ///
+    /// Inserts a new element into already sorted array while maintaining sorted
+    /// order. Then asserts that the item was inserted correctly.
+    ///
+    /// ```
+    /// let mut s = vec![0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
+    /// let num = 14;
+    ///
+    /// let idx = s.binary_search(&num);
+    /// if let Ok(idx) | Err(idx) {
+    ///    s.insert(idx, num)
+    /// };
+    ///
+    /// assert_eq!(s[10], num)
+    /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn binary_search(&self, x: &T) -> Result<usize, usize>
         where T: Ord