From 0ab781214c3bc9a70a47c576406646b4361769e6 Mon Sep 17 00:00:00 2001
From: Corey Farwell <coreyf@rwell.org>
Date: Fri, 23 Dec 2016 12:18:40 -0800
Subject: [PATCH] Clarify behavior of `VecDeque::insert`.

Fixes https://github.com/rust-lang/rust/issues/37046.
---
 src/libcollections/vec_deque.rs | 20 ++++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/src/libcollections/vec_deque.rs b/src/libcollections/vec_deque.rs
index dbe3fec205cb2..cd18617f74c52 100644
--- a/src/libcollections/vec_deque.rs
+++ b/src/libcollections/vec_deque.rs
@@ -1232,9 +1232,8 @@ impl<T> VecDeque<T> {
         self.pop_front()
     }
 
-    /// Inserts an element at `index` within the `VecDeque`. Whichever
-    /// end is closer to the insertion point will be moved to make room,
-    /// and all the affected elements will be moved to new positions.
+    /// Inserts an element at `index` within the `VecDeque`, shifting all elements with indices
+    /// greater than or equal to `index` towards the back.
     ///
     /// Element at index 0 is the front of the queue.
     ///
@@ -1243,14 +1242,19 @@ impl<T> VecDeque<T> {
     /// Panics if `index` is greater than `VecDeque`'s length
     ///
     /// # Examples
+    ///
     /// ```
     /// use std::collections::VecDeque;
     ///
-    /// let mut buf = VecDeque::new();
-    /// buf.push_back(10);
-    /// buf.push_back(12);
-    /// buf.insert(1, 11);
-    /// assert_eq!(Some(&11), buf.get(1));
+    /// let mut vec_deque = VecDeque::new();
+    /// vec_deque.push_back('a');
+    /// vec_deque.push_back('b');
+    /// vec_deque.push_back('c');
+    ///
+    /// vec_deque.insert(1, 'd');
+    ///
+    /// let vec = vec_deque.into_iter().collect::<Vec<_>>();
+    /// assert_eq!(vec, ['a', 'd', 'b', 'c']);
     /// ```
     #[stable(feature = "deque_extras_15", since = "1.5.0")]
     pub fn insert(&mut self, index: usize, value: T) {