1 files changed, 26 insertions, 5 deletions

diff --git a/source/core.cpp b/source/core.cpp
index 7daf1ae..c97203e 100644
--- a/source/core.cpp
+++ b/source/core.cpp
@@ -22,9 +22,11 @@
 
 void jump(FuncList ip)
 {
+    // IP is incremented before its next execution.
     IP = ip - 1;
 }
 
+// LITERAL's run-time semantics: push the given value onto the stack.
 static auto literall = WordWrap<[] {
     *++SP = (Cell)*++IP;
 }>();
@@ -51,6 +53,7 @@ void addkey(int k)
 
 int key()
 {
+    // Block until input is available.
     while (!haskey())
         getinput();
 
@@ -81,11 +84,13 @@ void align()
 
 void word()
 {
+    // Skip leading whitespace.
     int k;
     do {
         k = key();
     } while (isspace(k));
 
+    // Collect the word's text.
     char *ptr;
     do {
         ptr = reinterpret_cast<char *>(HERE);
@@ -98,6 +103,8 @@ void word()
         k = key();
     } while (!isspace(k));
     addkey(k);
+
+    // Add a null terminator.
     ptr = reinterpret_cast<char *>(HERE);
     *ptr = '\0';
     ++HERE;
@@ -105,47 +112,61 @@ void word()
 
 void colon()
 {
+    // Collect (and store) the word's name.
     align();
     auto name = HERE;
     word();
     align();
 
+    // Build the Word structure.
     comma(HERE + 4 * sizeof(Cell)); // exec ptr
-    comma(name); // name ptr
-    *++SP = (Cell)comma(0); // link (filled by latest)
-    comma(0); // immediate
-
+    comma(name);                    // name ptr
+    *++SP = (Cell)comma(0);         // link (to be set by semic())
+    comma(0);                       // immediate
+
+    // The word's execution begins with a prologue that technically performs
+    // the "call" to this word.
+    // By including this in the word's definition, execution can avoid caring
+    // about if it is running words or routines (i.e. pre-defined words).
     comma((Cell)+[](FuncList *ip) {
         ++ip;
         *++RP = (Cell)IP;
         jump((FuncList)*ip);
     });
+    // The actual function list will begin one Cell beyond here.
     comma(HERE + sizeof(Cell));
 
+    // Enter compiling state.
     STATE = -1;
 }
 
 void semic()
 {
+    // Add exit routine.
     comma((Cell)fexit);
 
+    // Complete the new word's linkage to make it usable.
     auto link = (Cell *)*SP--;
     *link = LATEST;
     LATEST = (Cell)(link - 2);
 
+    // Exit compilation state.
     STATE = 0;
 }
 
-// : ' bl word find drop ;
+// TODO define in Forth? ": ' bl word find drop ;"
 void tick()
 {
+    // Get the name to look up.
     auto name = (char *)HERE;
     word();
 
+    // Look up the name and push the result.
     int len = HERE - (Cell)name - 1;
     auto word = find(name, len);
     *++SP = (Cell)word;
 
+    // Deallocate `name`.
     HERE = (Cell)name;
 }