From 8eef7d76cace596a551f0031f50eb48ab1386e35 Mon Sep 17 00:00:00 2001
From: Sameer Rahmani <lxsameer@gnu.org>
Date: Fri, 25 Dec 2020 23:20:15 +0000
Subject: [PATCH] [Bootstrap] Add minor comment to clearify 'instructions'

---
 bootstrap/pkg/core/eval.go         |  7 ++++++-
 bootstrap/pkg/core/instructions.go | 20 ++++++++++++++++++++
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/bootstrap/pkg/core/eval.go b/bootstrap/pkg/core/eval.go
index d874e15..a7dd0e4 100644
--- a/bootstrap/pkg/core/eval.go
+++ b/bootstrap/pkg/core/eval.go
@@ -547,7 +547,12 @@ tco:
 					}
 
 					rt.Stack.Push(fn)
-					body := append(fn.GetBody().ToSlice(), MakeStackPop(rt))
+					body := append(
+						fn.GetBody().ToSlice(),
+						// Add the PopStack instruction to clean up the stack after
+						// returning from the function.
+						MakeStackPop(rt),
+					)
 					changeExecutionScope(body, fnScope)
 					exprs = append(body, restOfExprs(exprs, i)...)
 					goto body // rewrite
diff --git a/bootstrap/pkg/core/instructions.go b/bootstrap/pkg/core/instructions.go
index a88058b..0834e9a 100644
--- a/bootstrap/pkg/core/instructions.go
+++ b/bootstrap/pkg/core/instructions.go
@@ -18,6 +18,18 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 package core
 
+// Instructions Implementation:
+// * Instructions are expressions as well but they are not doing
+//   anything special by themselves.
+// * We need them to be expressions because we need to process
+//   them as part of the evaluation loop
+// * We use instructions as nodes in the AST to instruct Serene
+//   to do specific tasks after rewriting the AST. For example
+//   `PopStack` instructs Serene to simply pop a call from the
+//   call stack.
+// * Instructions doesn't return a value and should not alter
+//   the return value of the eval loop. But they might interrupt
+//   the loop by raising an error `IError`.
 import (
 	"fmt"
 
@@ -27,13 +39,20 @@ import (
 
 type instructionType int
 
+// Instruction types
 const (
+	// Pop a function from the call stack. We use this
+	// instruction at the end of function bodies. So
+	// function bodies will clean up after themselves
 	PopStack instructionType = iota
 )
 
 type Instruction struct {
+	// Just to be compatible with IExpr ---
 	Node
 	ExecutionScope
+	// ------------------------------------
+
 	Type instructionType
 }
 
@@ -60,6 +79,7 @@ func MakeStackPop(rt *Runtime) IExpr {
 	}
 }
 
+// ProcessInstruction is the main function to process instructions
 func ProcessInstruction(rt *Runtime, form *Instruction) IError {
 	switch form.Type {
 	case PopStack: