diff --git a/otto_test.go b/otto_test.go
index 7354aac..21daf7b 100644
--- a/otto_test.go
+++ b/otto_test.go
@@ -1393,6 +1393,9 @@ func TestOttoRun(t *testing.T) {
 	})
 }
 
+// This generates functions to be used by the test below. The arguments are
+// `src`, which is something that otto can execute, and `expected`, which is
+// what the result of executing `src` should be.
 func makeTestOttoEvalFunction(src, expected interface{}) func(c FunctionCall) Value {
 	return func(c FunctionCall) Value {
 		v, err := c.Otto.Eval(src)
@@ -1425,6 +1428,15 @@ func TestOttoEval(t *testing.T) {
 		vm.Set("y2", makeTestOttoEvalFunction(`b`, "what"))
 		vm.Set("z2", makeTestOttoEvalFunction(`c`, false))
 
+		// note that these variables are defined in the scope of function `t`,
+		// so would not usually be available to the functions called below.
+		//
+		// this is _not_ the recommended use case for `Eval` - instead it's
+		// intended to be used in `debugger` handlers. this code here is the
+		// equivalent of reading behind the current stack frame in C...
+		// technically valid, but completely insane.
+		//
+		// makes for a good test case though.
 		_, err := vm.Run(`(function t() {
             var a = 1;
             var b = 'hello';
@@ -1442,6 +1454,8 @@ func TestOttoEval(t *testing.T) {
 		is(err, nil)
 	})
 
+	// this test makes sure that `Eval` doesn't explode if the VM doesn't have
+	// a scope other than global defined.
 	tt(t, func() {
 		vm := New()