Docstring improvement: Added explanation of function

The free::zip function had a short explanation. I went ahead
and fleshed it out a bit. I also placed the code example under the
`## Example` subheading.

Aslo, fixed errors in PR #633

src/free.rs

@@ -105,22 +105,28 @@ pub fn rev<I>(iterable: I) -> iter::Rev<I::IntoIter>
     iterable.into_iter().rev()
 }
 
-/// Iterate `i` and `j` in lock step.
+/// Returns an iterator pairing two iterators together in lock step.
+///
+/// `zip()` returns an iterator where each item consists of items from the _first_ and _second_ iterator. 
+/// The returned iterator has as many items as the shortest of the two iterators passed in.
 ///
 /// [`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 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) {
 ///     result.push((*a, *b));
 /// }
 /// assert_eq!(result, vec![(1, 'a'),(2, 'b'),(3, 'c')]);
 /// ```
+#[deprecated(note="Use std::iter::zip instead", since="1.59.0")]
 pub fn zip<I, J>(i: I, j: J) -> Zip<I::IntoIter, J::IntoIter>
     where I: IntoIterator,
           J: IntoIterator