From 26af55f5c63e248757ec2be72061e2bcfbc78331 Mon Sep 17 00:00:00 2001
From: Mara Bos <m-ou.se@m-ou.se>
Date: Mon, 7 Dec 2020 21:23:50 +0100
Subject: [PATCH] Improve documentation of Iterator::{fold, reduce}.

---
 library/core/src/iter/traits/iterator.rs | 21 ++++++++++++++++-----
 1 file changed, 16 insertions(+), 5 deletions(-)

diff --git a/library/core/src/iter/traits/iterator.rs b/library/core/src/iter/traits/iterator.rs
index 7a3700d69236..648895e12f1d 100644
--- a/library/core/src/iter/traits/iterator.rs
+++ b/library/core/src/iter/traits/iterator.rs
@@ -2028,7 +2028,8 @@ pub trait Iterator {
         self.try_fold((), call(f))
     }
 
-    /// An iterator method that applies a function, producing a single, final value.
+    /// Folds every element into an accumulator by applying an operation,
+    /// returning the final result.
     ///
     /// `fold()` takes two arguments: an initial value, and a closure with two
     /// arguments: an 'accumulator', and an element. The closure returns the value that
@@ -2049,6 +2050,9 @@ pub trait Iterator {
     /// may not terminate for infinite iterators, even on traits for which a
     /// result is determinable in finite time.
     ///
+    /// Note: [`reduce()`] can be used to use the first element as the initial
+    /// value, if the accumulator type and item type is the same.
+    ///
     /// # Note to Implementors
     ///
     /// Several of the other (forward) methods have default implementations in
@@ -2104,6 +2108,8 @@ pub trait Iterator {
     /// // they're the same
     /// assert_eq!(result, result2);
     /// ```
+    ///
+    /// [`reduce()`]: Iterator::reduce
     #[doc(alias = "reduce")]
     #[doc(alias = "inject")]
     #[inline]
@@ -2120,10 +2126,15 @@ pub trait Iterator {
         accum
     }
 
-    /// The same as [`fold()`], but uses the first element in the
-    /// iterator as the initial value, folding every subsequent element into it.
-    /// If the iterator is empty, return [`None`]; otherwise, return the result
-    /// of the fold.
+    /// Reduces the elements to a single one, by repeatedly applying a reducing
+    /// operation.
+    ///
+    /// If the iterator is empty, returns [`None`]; otherwise, returns the
+    /// result of the reduction.
+    ///
+    /// For iterators with at least one element, this is the same as [`fold()`]
+    /// with the first element of the iterator as the initial value, folding
+    /// every subsequent element into it.
     ///
     /// [`fold()`]: Iterator::fold
     ///