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

src/ir/eval.rs

@@ -4,6 +4,10 @@ use crate::ir::{Expression, Program, Statement};
 use super::{Primitive, ValueOrRef};
 
 impl Program {
+    /// Evaluate the program, returning either an error or a string containing everything
+    /// the program printed out.
+    /// 
+    /// The print outs will be newline separated, with one print out per line.
     pub fn eval(&self) -> Result<String, EvalError> {
         let mut env = EvalEnvironment::empty();
         let mut stdout = String::new();
@@ -39,6 +43,9 @@ impl Expression {
             Expression::Primitive(_, op, args) => {
                 let mut arg_values = Vec::with_capacity(args.len());
 
+                // we implement primitive operations by first evaluating each of the
+                // arguments to the function, and then gathering up all the values
+                // produced.
                 for arg in args.iter() {
                     match arg {
                         ValueOrRef::Ref(_, n) => arg_values.push(env.lookup(n.clone())?),
@@ -48,6 +55,8 @@ impl Expression {
                     }
                 }
 
+                // and then finally we call `calculate` to run them. trust me, it's nice
+                // to not have to deal with all the nonsense hidden under `calculate`.
                 match op {
                     Primitive::Plus => Ok(Value::calculate("+", arg_values)?),
                     Primitive::Minus => Ok(Value::calculate("-", arg_values)?),