Document some of the IR; not much to say, actually.

src/ir/ast.rs

@@ -1,3 +1,4 @@
+use crate::syntax::Location;
 use internment::ArcIntern;
 use pretty::{DocAllocator, Pretty};
 use proptest::{
@@ -5,13 +6,18 @@ use proptest::{
     strategy::{BoxedStrategy, Strategy},
 };
 
-use crate::syntax::Location;
-
+/// We're going to represent variables as interned strings.
+/// 
+/// These should be fast enough for comparison that it's OK, since it's going to end up
+/// being pretty much the pointer to the string.
 type Variable = ArcIntern<String>;
 
+/// The representation of a program within our IR. For now, this is exactly one file.
 #[derive(Debug)]
 pub struct Program {
-    pub statements: Vec<Statement>,
+    // For now, a program is just a vector of statements. In the future, we'll probably
+    // extend this to include a bunch of other information, but for now: just a list.
+    pub(crate) statements: Vec<Statement>,
 }
 
 impl<'a, 'b, D, A> Pretty<'a, D, A> for &'b Program
@@ -23,6 +29,8 @@ where
         let mut result = allocator.nil();
 
         for stmt in self.statements.iter() {
+            // there's probably a better way to do this, rather than constantly
+            // adding to the end, but this works.
             result = result
                 .append(stmt.pretty(allocator))
                 .append(allocator.text(";"))
@@ -44,6 +52,10 @@ impl Arbitrary for Program {
     }
 }
 
+/// The representation of a statement in the language.
+/// 
+/// For now, this is either a binding site (`x = 4`) or a print statement
+/// (`print x`). Someday, though, more!
 #[derive(Debug)]
 pub enum Statement {
     Binding(Location, Variable, Expression),
@@ -71,6 +83,7 @@ where
     }
 }
 
+/// The representation of an expression.
 #[derive(Debug)]
 pub enum Expression {
     Value(Location, Value),