Fix some holes in documentation (#720)

* Add examples to error type docs

* Add relevant links in error type docs

* Fix Simple::found docs to match Rich::found docs

* Add example to Parser::into_iter docs

* Add example to Parser::to_slice docs

* Fix cargo fmt not liking my trailing whitespace in comments (does it even matter?...)

* Replace into_iter doc example

Author: benjamin-cates

src/error.rs

@@ -86,6 +86,17 @@ pub trait Error<'a, I: Input<'a>>:
 
 /// A ZST error type that tracks only whether a parse error occurred at all. This type is for when
 /// you want maximum parse speed, at the cost of all error reporting.
+///
+/// # Examples
+///
+/// ```
+/// use chumsky::prelude::*;
+///
+/// let parser = just::<_, _, extra::Err<EmptyErr>>("valid");
+/// let error = parser.parse("invalid").into_errors()[0];
+///
+/// assert_eq!(error, EmptyErr::default());
+/// ```
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[derive(PartialEq, Eq, PartialOrd, Ord, Debug, Copy, Clone, Default)]
 pub struct EmptyErr(());
@@ -109,8 +120,19 @@ impl fmt::Display for EmptyErr {
     }
 }
 
-/// A very cheap error type that tracks only the error span. This type is most useful when you want fast parsing but do
-/// not particularly care about the quality of error messages.
+/// A very cheap error type that tracks only the error span ([`SimpleSpan`] by default).
+/// This type is most useful when you want fast parsing but do not particularly care about the quality of error messages.
+///
+/// # Examples
+///
+/// ```
+/// use chumsky::prelude::*;
+///
+/// let parser = just::<_, _, extra::Err<Cheap>>("+");
+/// let error = parser.parse("-").into_errors()[0];
+///
+/// assert_eq!(error.span(), &SimpleSpan::new(0,1));
+/// ```
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[derive(Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
 pub struct Cheap<S = SimpleSpan<usize>> {
@@ -119,6 +141,8 @@ pub struct Cheap<S = SimpleSpan<usize>> {
 
 impl<S> Cheap<S> {
     /// Get the span than that error related to.
+    ///
+    /// If the span type is unspecified, it is [`SimpleSpan`].
     pub fn span(&self) -> &S {
         &self.span
     }
@@ -156,8 +180,20 @@ where
     }
 }
 
-/// A simple error type that tracks the error span and found token. This type is most useful when you want fast parsing
+/// A simple error type that tracks the error span ([`SimpleSpan`] by default) and found token. This type is most useful when you want fast parsing
 /// but do not particularly care about the quality of error messages.
+///
+/// # Examples
+///
+/// ```
+/// use chumsky::prelude::*;
+///
+/// let parser = just::<_, _, extra::Err<Simple<char>>>("+");
+/// let error = parser.parse("-").into_errors()[0];
+///
+/// assert_eq!(error.span(), &SimpleSpan::new(0,1));
+/// assert_eq!(error.found(), Some(&'-'));
+/// ```
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[derive(Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
 pub struct Simple<'a, T, S = SimpleSpan<usize>> {
@@ -167,11 +203,13 @@ pub struct Simple<'a, T, S = SimpleSpan<usize>> {
 
 impl<T, S> Simple<'_, T, S> {
     /// Get the span than that error related to.
+    ///
+    /// If the span type is unspecified, it is [`SimpleSpan`].
     pub fn span(&self) -> &S {
         &self.span
     }
 
-    /// Get the token, if any, that was found at the error location.
+    /// Get the token found by this error when parsing. `None` implies that the error expected the end of input.
     pub fn found(&self) -> Option<&T> {
         self.found.as_deref()
     }
@@ -537,6 +575,23 @@ where
 ///
 /// Please note that it uses a [`Vec`] to remember expected symbols. If you find this to be too slow, you can
 /// implement [`Error`] for your own error type or use [`Simple`] instead.
+///
+/// This error type stores a span ([`SimpleSpan`] by default), a [`RichReason`], and a list of expected [`RichPattern`] with their spans.
+///
+/// # Examples
+///
+/// ```
+/// use chumsky::prelude::*;
+/// use chumsky::error::{RichReason, RichPattern};
+///
+/// let parser = one_of::<_, _, extra::Err<Rich<char>>>("1234");
+/// let error = parser.parse("5").into_errors()[0].clone();
+///
+/// assert_eq!(error.span(), &SimpleSpan::new(0,1));
+/// assert!(matches!(error.reason(), &RichReason::ExpectedFound {..}));
+/// assert_eq!(error.found(), Some(&'5'));
+///
+/// ```
 #[derive(Clone, PartialEq, Eq, Hash)]
 pub struct Rich<'a, T, S = SimpleSpan<usize>> {
     span: S,
@@ -574,6 +629,8 @@ impl<'a, T, S> Rich<'a, T, S> {
     }
 
     /// Get the span associated with this error.
+    ///
+    /// If the span type is unspecified, it is [`SimpleSpan`].
     pub fn span(&self) -> &S {
         &self.span
     }

src/lib.rs

@@ -452,6 +452,34 @@ pub trait Parser<'src, I: Input<'src>, O, E: ParserExtra<'src, I> = extra::Defau
 
     /// Convert the output of this parser into a slice of the input, based on the current parser's
     /// span.
+    ///
+    /// Note: unlike the parser `.repeated().collect()`, this method includes all tokens that are
+    /// "ignored" by the parser, including any padding, separators, and sub-parsers with
+    /// [`Parser::ignored`], [`Parser::ignore_then`], and [`Parser::then_ignore`].
+    ///
+    /// # Examples
+    /// Example with input of type `&str` (token type is `char`).
+    /// ```
+    /// # use chumsky::prelude::*;
+    /// // Matches a number with underscores that is surrounded by apostrophes.
+    /// let quoted_numeric = any::<&str, extra::Err<Simple<char>>>()
+    ///     .filter(|c: &char| c.is_digit(10))
+    ///     .separated_by(just("_").repeated().at_most(1))
+    ///     .to_slice()
+    ///     .padded_by(just("'"));
+    /// assert_eq!(quoted_numeric.parse("'1_23'").into_result(), Ok("1_23"));
+    /// ```
+    /// Example with input of type `&[u32]` (token type is `u32`).
+    /// ```
+    /// # use chumsky::prelude::*;
+    /// // Matches even numbers, then ignoring the rest of the input when an odd number is reached.
+    /// let even_matcher = any::<&[u32], extra::Err<Simple<u32>>>()
+    ///     .filter(|c: &u32| c % 2 == 0)
+    ///     .repeated()
+    ///     .to_slice()
+    ///     .lazy();
+    /// assert_eq!(even_matcher.parse(&[2, 4, 8, 5, 6]).unwrap(), &[2, 4, 8]);
+    /// ```
     fn to_slice(self) -> ToSlice<Self, O>
     where
         Self: Sized,
@@ -2036,7 +2064,24 @@ pub trait Parser<'src, I: Input<'src>, O, E: ParserExtra<'src, I> = extra::Defau
     /// The resulting iterable parser will emit each element of the output type in turn.
     ///
     /// This is *broadly* analogous to functions like [`Vec::into_iter`], but operating at the level of parser outputs.
-    // TODO: Example
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use chumsky::prelude::*;
+    /// // Parses whole integers
+    /// let num = text::int::<&str, extra::Default>(10).padded().map(|x: &str| x.parse::<u64>().unwrap());
+    /// // Parses a range like `0..4` into a vector like `[0, 1, 2, 3]`
+    /// let range = num.then_ignore(just("..")).then(num)
+    ///     .map(|(x, y)| x..y)
+    ///     .into_iter()
+    ///     .collect::<Vec<u64>>();
+    /// // Parses a list of numbers into a vector
+    /// let list = num.separated_by(just(',')).collect::<Vec<u64>>();
+    /// let set = range.or(list);
+    /// assert_eq!(set.parse("0, 1, 2, 3").unwrap(), [0, 1, 2, 3]);
+    /// assert_eq!(set.parse("0..4").unwrap(), [0, 1, 2, 3]);
+    /// ```
     fn into_iter(self) -> IntoIter<Self, O>
     where
         Self: Sized,