From 892fb1828a3c3c07214e3d9a6fad644e471d9ac6 Mon Sep 17 00:00:00 2001
From: Niklas Elsbrock <mail@nelsbrock.de>
Date: Wed, 3 Apr 2024 19:10:50 +0200
Subject: [PATCH] rewrite documentation

---
 README.md  |  5 -----
 src/lib.rs | 22 ++++++++++++++++++----
 2 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 8091166..684a625 100644
--- a/README.md
+++ b/README.md
@@ -2,11 +2,6 @@
 An iterator adaptor for Rust that accumulates the elements from the base iterator
 using the provided closure.
 
-This is similar to `fold()`, but instead of returning the final accumulated result, it returns an
-iterator that yields the current accumulated value for each iteration. In other words, the last
-element yielded by `accumulate()` is what would have been returned by `fold()` if it was used
-instead.
-
 ## Example
 
 ```rust
diff --git a/src/lib.rs b/src/lib.rs
index 1f04c31..8210f92 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -4,15 +4,28 @@
 //! This crate provides [`accumulate()`], an iterator adaptor that accumulates the elements from the
 //! base iterator using the provided closure.
 //!
-//! [`accumulate()`] is similar to [`fold()`], but instead of returning the final accumulated
-//! result, it returns an iterator that yields the current accumulated value for each iteration.
-//! In other words, the last element yielded by [`accumulate()`] is what would have been returned
-//! by [`fold()`] if it was used instead.
+//! [`accumulate()`] takes two arguments: an initial value, and a closure with two arguments:
+//! an 'accumulator', and an element.
+//!
+//! The initial value is the value the accumulator will have when the closure is first called.
+//! On each call to [`next()`], the closure is executed with the current accumulator and the element
+//! yielded by the upstream iterator. The return value of the closure is then set as the new value
+//! of the accumulator and returned to the caller.
+//!
+//! Since the accumulated value needs to be both stored as the accumulator *and* returned to the
+//! caller, the accumulator type must implement [`Clone`].
 //!
 //! The returned iterator is **not** fused and it is not specified what happens when the base
 //! iterator returns [`None`].
 //! If you want a fused iterator, use [`fuse()`].
 //!
+//! # Differences to [`fold()`]
+//!
+//! In principle, [`accumulate()`] is similar to [`fold()`]. However, instead of returning the final
+//! accumulated result, it returns an iterator that yields the current value of the accumulator for
+//! each iteration. In other words, the last element yielded by [`accumulate()`] is what would have
+//! been returned by [`fold()`] if it had been used instead.
+//!
 //! # Examples
 //!
 //! ```
@@ -31,6 +44,7 @@
 //!
 //! [`accumulate()`]: IterAccumulate::accumulate
 //! [`fold()`]: Iterator::fold
+//! [`next()`]: Iterator::next
 //! [`fuse()`]: Iterator::fuse
 
 use core::fmt;