From eefbcc8ae2b5f3341ef152ee9ab55a402847ac6d Mon Sep 17 00:00:00 2001
From: Sebastian Hugentobler <shu@vanwa.ch>
Date: Mon, 26 May 2025 12:31:51 +0200
Subject: [PATCH] documentation run

---
 src/interpreter.rs | 22 ++++++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/src/interpreter.rs b/src/interpreter.rs
index 7176892..0388687 100644
--- a/src/interpreter.rs
+++ b/src/interpreter.rs
@@ -49,8 +49,11 @@ pub enum InterpreterError {
 /// Interpreter for the Lox language that executes statements and evaluates expressions.
 #[derive(Debug)]
 pub struct Interpreter {
+    /// Global environment containing built-in functions and top-level variables
     pub globals: Rc<RefCell<Environment>>,
+    /// Current environment for variable lookups and assignments
     environment: Rc<RefCell<Environment>>,
+    /// Map of expressions to their lexical distance for variable resolution
     locals: HashMap<Expression, usize>,
 }
 
@@ -76,7 +79,8 @@ impl Default for Interpreter {
 }
 
 impl Interpreter {
-    /// Try to evaluate an expression and return its result.
+    /// Execute a list of statements in sequence.
+    /// Log errors but continue execution.
     pub fn run(&mut self, statements: Vec<Statement>) -> Result<(), InterpreterError> {
         for stmt in statements {
             match self.execute(&stmt) {
@@ -88,11 +92,12 @@ impl Interpreter {
         Ok(())
     }
 
+    /// Record the resolved lexical depth for a variable reference.
     pub fn resolve(&mut self, expression: Expression, depth: usize) {
         self.locals.insert(expression, depth);
     }
 
-    ///Execute a statement.
+    /// Execute a statement and return its result value, if any.
     fn execute(&mut self, statement: &Statement) -> Result<Option<Value>, InterpreterError> {
         match statement {
             Statement::Block(statements) => {
@@ -154,6 +159,8 @@ impl Interpreter {
         Ok(None)
     }
 
+    /// Define a new class with methods and optional inheritance.
+    /// Handle superclass setup and method capturing.
     fn class(
         &mut self,
         name: &Token,
@@ -259,6 +266,7 @@ impl Interpreter {
 
     /// Call a callable if it is one (meaning it starts with a LeftParen after an identifier),
     /// otherwise evaluate the expression.
+    /// Evaluate the callee and all arguments before making the call.
     fn call(
         &mut self,
         callee: &Expression,
@@ -280,6 +288,8 @@ impl Interpreter {
         }
     }
 
+    /// Get a property from an object instance.
+    /// Properties can be fields or methods.
     fn get(&mut self, object: &Expression, name: &Token) -> Result<Value, InterpreterError> {
         match self.evaluate(object)? {
             Value::Instance(instance) => Ok(instance.borrow().get(name, instance.clone())?),
@@ -287,6 +297,7 @@ impl Interpreter {
         }
     }
 
+    /// Set a property on an object instance to a new value.
     fn set(
         &mut self,
         object: &Expression,
@@ -304,6 +315,7 @@ impl Interpreter {
         }
     }
 
+    /// Handle super expressions to access methods from a superclass.
     fn super_expr(
         &mut self,
         expression: &Expression,
@@ -423,7 +435,7 @@ impl Interpreter {
         Ok(None)
     }
 
-    /// Execute the body as long as the condition evaluates to true.
+    /// Execute the body as long as the loop condition evaluates to true.
     fn while_statement(
         &mut self,
         condition: &Expression,
@@ -513,7 +525,7 @@ impl Interpreter {
         }
     }
 
-    /// Get the value of a variable.
+    /// Evaluate a variable reference expression.
     fn var_expression(
         &mut self,
         name: &Token,
@@ -522,6 +534,8 @@ impl Interpreter {
         self.lookup_var(name, expression)
     }
 
+    /// Look up a variable's value using static analysis information.
+    /// Use the resolved lexical distance if available, otherwise check globals.
     fn lookup_var(
         &mut self,
         name: &Token,