From 8bd5d3632fc5585296b71666aad990defa7a6e2d Mon Sep 17 00:00:00 2001
From: Caleb Jones <code@calebjones.net>
Date: Fri, 30 Dec 2016 16:17:08 -0500
Subject: [PATCH] Document ParseResult

---
 src/lib.rs    |  2 +-
 src/parser.rs | 16 +++++++++++++---
 2 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index 48cf130..792f09b 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,6 +1,6 @@
 //! A lightweight S-expression parser intended for language implementation.
 
-// #![warn(missing_docs)]
+#![warn(missing_docs)]
 #![deny(unsafe_code)]
 
 pub mod sexp;
diff --git a/src/parser.rs b/src/parser.rs
index e5ab66e..2ae99b7 100644
--- a/src/parser.rs
+++ b/src/parser.rs
@@ -4,14 +4,24 @@ use span::{Span, ByteSpan};
 
 // Parsing Types ///////////////////////////////////////////////////////////////
 
+/// Represents what to do next in partially completed parsing.
+///
+/// `ParseResult` is returned from all intermediate parsers. If you just want to
+/// get back parsed S-expressions, you won't need to worry about this type since
+/// the top level parsers just return a `Result`.
+///
+/// If the parser failed to produce a result, it will return `Error`, and if it
+/// succeeded we'll get the `Done` variant containing the value produced and the
+/// rest of the text to work on.
 #[derive(Debug, PartialEq, Eq, Clone)]
 pub enum ParseResult<'a, T, E> {
+    /// The parser succeeded, this contains first the un-consumed portion of the
+    /// input then the result produced by parsing.
     Done(&'a str, T),
+    /// The parser failed, the `E` represents the reason for the failure.
     Error(E),
 }
 
-use self::ParseResult::*;
-
 /// Indicates how parsing failed.
 #[derive(Debug, PartialEq, Eq, Clone)]
 pub enum ParseError<Loc=ByteSpan> where Loc: Span {
@@ -23,8 +33,8 @@ pub enum ParseError<Loc=ByteSpan> where Loc: Span {
     Symbol(Box<ParseError>, Loc),
     Number(Box<ParseError>, Loc),
     Unexpected(char, Loc::Begin),
-    Unimplemented,
 }
+use self::ParseResult::*;
 
 
 // Parsing Utilities ///////////////////////////////////////////////////////////
-- 
2.43.2