- /// When the iterator **is** dropped, all elements in the range are removed
- /// from the vector, even if the iterator was not fully consumed. If the
- /// iterator **is not** dropped (with [`mem::forget`] for example), it is
- /// unspecified how many elements are removed.
+ /// The returned iterator keeps a mutable borrow on the vector to optimize
+ /// its implementation.