From 42764765d2a6741ede9e87ce18635fb77a8985fd Mon Sep 17 00:00:00 2001
From: Joel Montes de Oca <6587811+JoelMon@users.noreply.github.com>
Date: Mon, 11 Jul 2022 13:46:38 -0400
Subject: [PATCH] Docstring improvement: Added explanation of function

Added example and link to std::iter::zip
---
 src/free.rs | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/src/free.rs b/src/free.rs
index d93eb2bef..4c657f25a 100644
--- a/src/free.rs
+++ b/src/free.rs
@@ -105,22 +105,23 @@ pub fn rev<I>(iterable: I) -> iter::Rev<I::IntoIter>
     iterable.into_iter().rev()
 }
 
-/// Iterate `i` and `j` in lock step.
+/// Converts the arguments to iterators and zips them.
 ///
 /// [`IntoIterator`] enabled version of [`Iterator::zip`].
+/// 
+/// ## Example
 ///
 /// ```
 /// use itertools::zip;
 ///
-/// let data_1 = [1, 2, 3, 4, 5];
-/// let data_2 = ['a', 'b', 'c'];
 /// let mut result: Vec<(i32, char)> = Vec::new();
 ///
-/// for (a, b) in zip(&data_1, &data_2) {
+/// for (a, b) in zip(&[1, 2, 3, 4, 5], &['a', 'b', 'c']) {
 ///     result.push((*a, *b));
 /// }
 /// assert_eq!(result, vec![(1, 'a'),(2, 'b'),(3, 'c')]);
 /// ```
+#[deprecated(note="Use [std::iter::zip](https://doc.rust-lang.org/std/iter/fn.zip.html) instead", since="0.10.4")]
 pub fn zip<I, J>(i: I, j: J) -> Zip<I::IntoIter, J::IntoIter>
     where I: IntoIterator,
           J: IntoIterator