Switched to zero-width EOI spans for strings, better docs

src/chain.rs

@@ -1,3 +1,11 @@
+//! Traits that allow chaining parser outputs together.
+//!
+//! *“And what’s happened to the Earth?” “Ah. It’s been demolished.” “Has it,” said Arthur levelly. “Yes. It just
+//! boiled away into space.” “Look,” said Arthur, “I’m a bit upset about that.”*
+//!
+//! You usually don't need to interact with this trait, or even import it. It's only public so that you can see which
+//! types implement it. See [`Parser::chain`](super::Parser) for examples of its usage.
+
 mod private {
     pub trait Sealed<T> {}
 

src/combinator.rs

@@ -1,3 +1,10 @@
+//! Combinators that allow combining and extending existing parsers.
+//!
+//! *“Ford... you're turning into a penguin. Stop it.”*
+//!
+//! Although it's *sometimes* useful to be able to name their type, most of these parsers are much easier to work with
+//! when accessed through their respective methods on [`Parser`].
+
 use super::*;
 
 /// See [`Parser::ignored`].

src/debug.rs

@@ -1,3 +1,8 @@
+//! Utilities for debugging parsers.
+//!
+//! *“He was staring at the instruments with the air of one who is trying to convert Fahrenheit to centigrade in his
+//! head while his house is burning down.”*
+
 use super::*;
 
 use std::{borrow::Cow, panic::Location};

src/error.rs

@@ -1,3 +1,11 @@
+//! Error types, traits and utilities.
+//!
+//! *“I like the cover," he said. "Don't Panic. It's the first helpful or intelligible thing anybody's said to me all
+//! day.”*
+//!
+//! You can implement the [`Error`] trait to create your own parser errors, or you can use one provided by the crate
+//! like [`Simple`] or [`Cheap`].
+
 use super::*;
 use std::{collections::HashSet, hash::Hash};
 

src/lib.rs

@@ -3,23 +3,14 @@
 #![deny(missing_docs)]
 #![allow(deprecated)] // TODO: Don't allow this
 
-/// Traits that allow chaining parser outputs together.
 pub mod chain;
-/// Combinators that allow combining and extending existing parsers.
 pub mod combinator;
-/// Utilities for debugging parsers.
 pub mod debug;
-/// Error types, traits and utilities.
 pub mod error;
-/// Parser primitives that accept specific token patterns.
 pub mod primitive;
-/// Types and traits that facilitate error recovery.
 pub mod recovery;
-/// Recursive parsers (parser that include themselves within their patterns).
 pub mod recursive;
-/// Types and traits related to spans.
 pub mod span;
-/// Token streams and behaviours.
 pub mod stream;
 pub mod text;
 
@@ -56,6 +47,9 @@ use std::{
 };
 
 /// Commonly used functions, traits and types.
+///
+/// *Listen, three eyes,” he said, “don’t you try to outweird me, I get stranger things than you free with my breakfast
+/// cereal.”*
 pub mod prelude {
     pub use super::{
         error::{Error as _, Simple},

src/primitive.rs

@@ -1,3 +1,18 @@
+//! Parser primitives that accept specific token patterns.
+//!
+//! *“These creatures you call mice, you see, they are not quite as they appear. They are merely the protrusion into
+//! our dimension of vastly hyperintelligent pandimensional beings.”*
+//!
+//! Chumsky parsers are created by combining together smaller parsers. Right at the bottom of the pile are the parser
+//! primitives, a parser developer's bread & butter. Each of these primitives are very easy to understand in isolation,
+//! usually only doing one thing.
+//!
+//! ## The Important Ones
+//!
+//! - [`just`]: parses a specific input or sequence of inputs
+//! - [`filter`]: parses a single input, if the given filter function returns `true`
+//! - [`end`]: parses the end of input (i.e: if there any more inputs, this parse fails)
+
 use super::*;
 
 /// See [`custom`].

src/recovery.rs

@@ -1,3 +1,7 @@
+//! Types and traits that facilitate error recovery.
+//!
+//! *“Do you find coming to terms with the mindless tedium of it all presents an interesting challenge?”*
+
 use super::*;
 
 /// A trait implemented by error recovery strategies.

src/recursive.rs

@@ -1,3 +1,13 @@
+//! Recursive parsers (parser that include themselves within their patterns).
+//!
+//! *“It's unpleasantly like being drunk."
+//! "What's so unpleasant about being drunk?"
+//! "You ask a glass of water.”*
+//!
+//! The [`recursive`] function covers most cases, but sometimes it's necessary to manually control the declaration and
+//! definition of parsers more corefully, particularly for mutually-recursive parsers. In such cases, the functions on
+//! [`Recursive`] allow for this.
+
 use super::*;
 
 use std::rc::{Rc, Weak};

src/span.rs

@@ -1,3 +1,9 @@
+//! Types and traits related to spans.
+//!
+//! *“We demand rigidly defined areas of doubt and uncertainty!”*
+//!
+//! You can use the [`Span`] trait to connect up chumsky to your compiler's knowledge of the input source.
+
 use std::ops::Range;
 
 /// A trait that describes a span over a particular range of inputs.

src/stream.rs

@@ -1,3 +1,10 @@
+//! Token streams and tools converting to and from them..
+//!
+//! *“What’s up?” “I don’t know,” said Marvin, “I’ve never been there.”*
+//!
+//! [`Stream`] is the primary type used to feed input data into a chumsky parser. You can create them in a number of
+//! ways: from strings, iterators, arrays, etc.
+
 use super::*;
 
 trait StreamExtend<T>: Iterator<Item = T> {
@@ -238,7 +245,7 @@ impl<'a> From<&'a str>
     fn from(s: &'a str) -> Self {
         let len = s.chars().count();
         Self::from_iter(
-            len..len + 1,
+            len..len,
             Box::new(s.chars().enumerate().map(|(i, c)| (c, i..i + 1))),
         )
     }
@@ -252,7 +259,7 @@ impl<'a> From<String>
     fn from(s: String) -> Self {
         let chars = s.chars().collect::<Vec<_>>();
         Self::from_iter(
-            chars.len()..chars.len() + 1,
+            chars.len()..chars.len(),
             Box::new(chars.into_iter().enumerate().map(|(i, c)| (c, i..i + 1))),
         )
     }

src/text.rs

@@ -1,5 +1,8 @@
 //! Text-specific parsers and utilities.
 //!
+//! *“Ford!" he said, "there's an infinite number of monkeys outside who want to talk to us about this script for
+//! Hamlet they've worked out.”*
+//!
 //! The parsers in this module are generic over both Unicode ([`char`]) and ASCII ([`u8`]) characters. Most parsers take
 //! a type parameter, `C`, that can be either [`u8`] or [`char`] in order to handle either case.
 //!