From 94326f3410a9028905b52c45dc4eb1e2fa32c186 Mon Sep 17 00:00:00 2001
From: Joel Montes de Oca <6587811+JoelMon@users.noreply.github.com>
Date: Mon, 11 Jul 2022 14:21:36 -0400
Subject: [PATCH] Improved docstrings for `free::chain`

- Improved the description of the function and added example.
- Fixed errors in PR
- Implemented suggestions by phimuemue
---
 src/free.rs | 12 +++++++++---
 src/lib.rs  |  4 ++--
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/src/free.rs b/src/free.rs
index d93eb2bef..041bbdb26 100644
--- a/src/free.rs
+++ b/src/free.rs
@@ -128,17 +128,23 @@ pub fn zip<I, J>(i: I, j: J) -> Zip<I::IntoIter, J::IntoIter>
     i.into_iter().zip(j)
 }
 
-/// Create an iterator that first iterates `i` and then `j`.
+
+/// Takes two iterators and creates a new iterator over both in sequence. 
 ///
 /// [`IntoIterator`] enabled version of [`Iterator::chain`].
 ///
+/// ## Example
 /// ```
 /// use itertools::chain;
+/// 
+/// let mut result:Vec<i32> = Vec::new();
 ///
-/// for elt in chain(&[1, 2, 3], &[4]) {
-///     /* loop body */
+/// for element in chain(&[1, 2, 3] , &[4]) {
+///     result.push(*element);
 /// }
+/// assert_eq!(result, vec![1, 2, 3, 4]);
 /// ```
+#[deprecated(note="Use std::iter::Chain instead", since="1.0.0")]
 pub fn chain<I, J>(i: I, j: J) -> iter::Chain<<I as IntoIterator>::IntoIter, <J as IntoIterator>::IntoIter>
     where I: IntoIterator,
           J: IntoIterator<Item = I::Item>
diff --git a/src/lib.rs b/src/lib.rs
index 5cca5d99f..f91968870 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -2271,7 +2271,7 @@ pub trait Itertools : Iterator {
     /// ```
     ///
     /// Which, for non-associative functions, will typically produce a different
-    /// result than the linear call tree used by `fold1`:
+    /// result than the linear call tree used by [`Iterator::reduce`]:
     ///
     /// ```text
     /// 1 2 3 4 5 6 7
@@ -2279,7 +2279,7 @@ pub trait Itertools : Iterator {
     /// └─f─f─f─f─f─f
     /// ```
     ///
-    /// If `f` is associative, prefer the normal `fold1` instead.
+    /// If `f` is associative, prefer the normal [`Iterator::reduce`] instead.
     ///
     /// ```
     /// use itertools::Itertools;