move description and examples to crate-level docs

src/lib.rs

@@ -1,12 +1,44 @@
 #![no_std]
 #![warn(missing_docs)]
 
-//! This crate provides the [`accumulate()`](IterAccumulate::accumulate) iterator adaptor.
+//! 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.
+//!
+//! 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()`].
+//!
+//! # Examples
+//!
+//! ```
+//! use iter_accumulate::IterAccumulate;
+//!
+//! let input = [1, 2, 3, 4, 5];
+//! let mut iter = input.iter().accumulate(1, |acc, i| acc * i);
+//!
+//! assert_eq!(iter.next(), Some(1));
+//! assert_eq!(iter.next(), Some(2));
+//! assert_eq!(iter.next(), Some(6));
+//! assert_eq!(iter.next(), Some(24));
+//! assert_eq!(iter.next(), Some(120));
+//! assert_eq!(iter.next(), None);
+//! ```
+//!
+//! [`accumulate()`]: IterAccumulate::accumulate
+//! [`fold()`]: Iterator::fold
+//! [`fuse()`]: Iterator::fuse
+
+use core::fmt;
 
 /// An iterator adaptor that accumulates the elements from the base iterator using the provided
 /// closure.
 ///
-/// See [`IterAccumulate::accumulate()`] for more information.
+/// See the [crate-level documentation](crate) for more information.
 #[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
 #[derive(Clone)]
 pub struct Accumulate<I, B, F> {
@@ -70,33 +102,7 @@ pub trait IterAccumulate: Iterator {
     /// Creates 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
+    /// See the [crate-level documentation](crate) for more information.
-    /// 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.
-    ///
-    /// 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()`].
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// use iter_accumulate::IterAccumulate;
-    ///
-    /// let input = [1, 2, 3, 4, 5];
-    /// let mut iter = input.iter().accumulate(1, |acc, i| acc * i);
-    ///
-    /// assert_eq!(iter.next(), Some(1));
-    /// assert_eq!(iter.next(), Some(2));
-    /// assert_eq!(iter.next(), Some(6));
-    /// assert_eq!(iter.next(), Some(24));
-    /// assert_eq!(iter.next(), Some(120));
-    /// assert_eq!(iter.next(), None);
-    /// ```
-    ///
-    /// [`fold()`]: Iterator::fold
-    /// [`fuse()`]: Iterator::fuse
     #[inline]
     fn accumulate<B, F>(self, init: B, f: F) -> Accumulate<Self, B, F>
     where