Merge pull request #51 from FredTheDino/document/internal

document/internal

3 files changed, 25 insertions, 17 deletions

diff --git a/src/compiler.rs b/src/compiler.rs
index 4988c4d..dcd0317 100644
--- a/src/compiler.rs
+++ b/src/compiler.rs
@@ -161,12 +161,11 @@ macro_rules! push_scope {
     };
 }
 
+/// Helper function for adding operations to the given block.
 fn add_op(compiler: &Compiler, block: &mut Block, op: Op) -> usize {
     block.add(op, compiler.line())
 }
 
-
-
 impl Compiler {
     pub fn new(current_file: &Path, tokens: TokenStream) -> Self {
         Self {
@@ -209,6 +208,7 @@ impl Compiler {
         &mut self.frame_mut().stack
     }
 
+    /// Used to recover from a panic so the rest of the code can be parsed.
     fn clear_panic(&mut self) {
         if self.panic {
             self.panic = false;
@@ -257,6 +257,15 @@ impl Compiler {
         t
     }
 
+    /// The line of the current token.
+    fn line(&self) -> usize {
+        if self.curr < self.tokens.len() {
+            self.tokens[self.curr].1
+        } else {
+            self.tokens[self.tokens.len() - 1].1
+        }
+    }
+
     fn precedence(&self, token: Token) -> Prec {
         match token {
             Token::Star | Token::Slash => Prec::Factor,
@@ -279,14 +288,6 @@ impl Compiler {
         }
     }
 
-    fn line(&self) -> usize {
-        if self.curr < self.tokens.len() {
-            self.tokens[self.curr].1
-        } else {
-            self.tokens[self.tokens.len() - 1].1
-        }
-    }
-
     fn prefix(&mut self, token: Token, block: &mut Block) -> bool {
         match token {
             Token::Identifier(_) => self.variable_expression(block),
@@ -305,7 +306,6 @@ impl Compiler {
         return true;
     }
 
-
     fn infix(&mut self, token: Token, block: &mut Block) -> bool {
         match token {
             Token::Minus
@@ -430,6 +430,7 @@ impl Compiler {
         block.add_from(op, self.line());
     }
 
+    /// Entry point for all expression parsing.
     fn expression(&mut self, block: &mut Block) {
         match self.peek_four() {
             (Token::Fn, ..) => self.function(block),
@@ -516,6 +517,7 @@ impl Compiler {
         add_op(self, block, Op::Call(arity));
     }
 
+    // TODO(ed): de-complexify
     fn function(&mut self, block: &mut Block) {
         expect!(self, Token::Fn, "Expected 'fn' at start of function.");
 
@@ -809,6 +811,7 @@ impl Compiler {
 
     fn parse_type(&mut self) -> Result<Type, ()> {
         match self.peek() {
+
             Token::Fn => {
                 self.eat();
                 let mut params = Vec::new();
@@ -841,6 +844,7 @@ impl Compiler {
                 let f = Type::Function(params, Box::new(return_type));
                 Ok(f)
             }
+
             Token::LeftParen => {
                 self.eat();
                 let mut element = Vec::new();
@@ -857,6 +861,7 @@ impl Compiler {
                     }
                 }
             }
+
             Token::Identifier(x) => {
                 self.eat();
                 match x.as_str() {
@@ -868,7 +873,6 @@ impl Compiler {
                 }
             }
             _ => Err(()),
-
         }
     }
 
diff --git a/src/lib.rs b/src/lib.rs
index cfbbe50..d43cc8b 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -614,6 +614,7 @@ impl Block {
         }
     }
 
+    /// Used to create empty functions.
     pub fn empty_with_type(ty: &Type) -> Self {
         let mut block = Block::new("/empty/", Path::new(""), 0);
         block.ty = ty.clone();
diff --git a/src/vm.rs b/src/vm.rs
index 474c51d..eabe382 100644
--- a/src/vm.rs
+++ b/src/vm.rs
@@ -88,11 +88,13 @@ impl VM {
         }
     }
 
+    /// Tells the VM to dump all the blocks to STDOUT.
     pub fn print_blocks(mut self, b: bool) -> Self {
         self.print_blocks = b;
         self
     }
 
+    /// Tells the VM to dump all the ops as they are run to STDOUT.
     pub fn print_ops(mut self, b: bool) -> Self {
         self.print_ops = b;
         self
@@ -129,10 +131,6 @@ impl VM {
         (b, a)  // this matches the order they were on the stack
     }
 
-    fn _peek_up(&self, amount: usize) -> Option<&Value> {
-        self.stack.get(self.stack.len() - amount)
-    }
-
     fn frame(&self) -> &Frame {
         let last = self.frames.len() - 1;
         &self.frames[last]
@@ -148,8 +146,8 @@ impl VM {
         self.frame().block.borrow().ops[ip].clone()
     }
 
+    /// Stop the program, violently
     fn crash_and_burn(&self) -> ! {
-        println!("\n\n    !!!POPPING EMPTY STACK - DUMPING EVERYTHING!!!\n");
         self.print_stack();
         println!("\n");
         self.frame().block.borrow().debug_print();
@@ -169,6 +167,7 @@ impl VM {
         }
     }
 
+    /// Runs a single operation on the VM
     fn eval_op(&mut self, op: Op) -> Result<OpResult, Error> {
         match op {
             Op::Illegal => {
@@ -434,6 +433,7 @@ impl VM {
             self.frame().block.borrow().ops[self.frame().ip]);
     }
 
+    /// Initalizes the VM for running, run cannot be called before this.
     pub fn init(&mut self, prog: &Prog) {
         let block = Rc::clone(&prog.blocks[0]);
         self.blobs = prog.blobs.clone();
@@ -450,6 +450,7 @@ impl VM {
         });
     }
 
+    /// Simulates the program.
     pub fn run(&mut self) -> Result<OpResult, Error> {
 
         if self.print_blocks {
@@ -469,6 +470,7 @@ impl VM {
         }
     }
 
+    /// Checks the current operation for type errors.
     fn check_op(&mut self, op: Op) -> Result<(), Error> {
         match op {
             Op::Unreachable => {}
@@ -710,6 +712,7 @@ impl VM {
         errors
     }
 
+    /// Checks the program for type errors.
     pub fn typecheck(&mut self, prog: &Prog) -> Result<(), Vec<Error>> {
         let mut errors = Vec::new();