Add some explanatory comments

2 files changed, 18 insertions, 0 deletions

diff --git a/dhall_core/src/parser.rs b/dhall_core/src/parser.rs
index 357d006..b0741ed 100644
--- a/dhall_core/src/parser.rs
+++ b/dhall_core/src/parser.rs
@@ -8,6 +8,11 @@ use dhall_parser::{DhallParser, Rule};
 use crate::core;
 use crate::core::*;
 
+// This file consumes the parse tree generated by pest and turns it into
+// our own AST. All those custom macros should eventually moved into
+// their own crate because they are quite general and useful. For now they
+// are here and hopefully you can figure out how they work.
+
 pub type ParsedExpr = Expr<X, Import>;
 pub type BoxExpr = Box<ParsedExpr>;
 
diff --git a/dhall_parser/src/lib.rs b/dhall_parser/src/lib.rs
index 94b49b5..e0843af 100644
--- a/dhall_parser/src/lib.rs
+++ b/dhall_parser/src/lib.rs
@@ -1 +1,14 @@
+// This crate only contains the grammar-generated parser. The rest of the
+// parser is in dhall_core. This separation is because compiling the
+// grammar-generated parser is extremely slow. Eventually, the whole parser
+// should probably be moved to here.
+// See the https://pest.rs documentation for details on what this crate contains.
+// The pest file is auto-generated and is located at ./dhall.pest.
+// It is generated from grammar.abnf in a rather straightforward manner. Some
+// additional overrides are done in ../build.rs.
+// The lines that are commented out in ./dhall.pest.visibility are marked as
+// silent (see pest docs for what that means) in the generated pest file.
+// The abnf file has quite a lot of modifications compared to the one from
+// the standard. Hopefully those changes should be merged upstream, but for now
+// feel free to edit it to make parsing easier.
 include!(concat!(env!("OUT_DIR"), "/grammar.rs"));