Improve documentation

1 files changed, 15 insertions, 8 deletions

diff --git a/src/lib.rs b/src/lib.rs
index 7022d37..60d3546 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -23,15 +23,22 @@
 //! assert_eq!(iter.next(), None);
 //! ```
 //!
-//! # Rationale
+//! See the `examples` directory for a real world example.
 //!
-//! This library was created to process a large number of files returned by
-//! [walkdir](https://crates.io/crates/walkdir) in parallel, in order, and in constant space. It's
-//! API and dependencies were kept to a minimum to ease maintenance.
+//! # Features
+//!
+//! * Parseq utilizes a configurable number of worker threads
+//! * Parseq preserves the order of the original iterator
+//! * Parseq is lazy in the sense that it doesn't consume from the original iterator before [`next`](`Iterator::next`) is called for the first time
+//! * Parseq doesn't [`fuse`](`Iterator::fuse`) the original iterator
+//! * Parseq uses constant space: linear in the number of threads and the size of the buffer, not in the length of the possibly infinite original iterator
+//! * Parseq propagates panics from the given closure
+//!
+//! # Alternatives
 //!
 //! If you don't care about the order of the returned iterator you'll probably want to use
-//! [rayon](https://crates.io/crates/rayon) instead. If you do care about the order, take a look at
-//! [pariter](https://crates.io/crates/pariter). The latter provides more functionality than this
+//! [Rayon](https://crates.io/crates/rayon) instead. If you do care about the order, take a look at
+//! [Pariter](https://crates.io/crates/pariter). The latter provides more functionality than this
 //! crate and predates it.
 
 #![forbid(unsafe_code)]
@@ -55,7 +62,7 @@ pub trait ParallelIterator {
     ///
     /// * preserves the order of the original iterator
     /// * is lazy in the sense that it doesn't consume from the original iterator before [`next`](`Iterator::next`) is called for the first time
-    /// * doesn't fuse the original iterator
+    /// * doesn't [`fuse`](`Iterator::fuse`) the original iterator
     /// * uses constant space: linear in `threads` and `buffer_size`, not in the length of the possibly infinite original iterator
     /// * propagates panics from the given closure
     ///
@@ -103,7 +110,7 @@ pub trait ParallelIterator {
     ///
     /// * preserves the order of the original iterator
     /// * is lazy in the sense that it doesn't consume from the original iterator before [`next`](`Iterator::next`) is called for the first time
-    /// * doesn't fuse the original iterator
+    /// * doesn't [`fuse`](`Iterator::fuse`) the original iterator
     /// * uses constant space: linear in `threads` and `buffer_size`, not in the length of the possibly infinite original iterator
     /// * propagates panics from the given closure
     ///