From e41b124320011cb1451f9869710a110058ee95aa Mon Sep 17 00:00:00 2001
From: Clyne Sullivan <clyne@bitgloo.com>
Date: Sat, 11 Mar 2023 10:21:51 -0500
Subject: update documentation

---
 libalee/state.hpp | 36 +++++++++++++++++++++++++++---------
 1 file changed, 27 insertions(+), 9 deletions(-)

(limited to 'libalee/state.hpp')

diff --git a/libalee/state.hpp b/libalee/state.hpp
index 325f405..4c74f9a 100644
--- a/libalee/state.hpp
+++ b/libalee/state.hpp
@@ -34,9 +34,8 @@ class State
 public:
     Addr ip = 0;
     Dictionary& dict;
-    void (*input)(State&);
-
-    std::jmp_buf jmpbuf = {};
+    void (*input)(State&); // User-provided function to collect "stdin" input.
+    std::jmp_buf jmpbuf = {}; // Used when catching execution errors.
 
     constexpr State(Dictionary& d, void (*i)(State&)):
         dict(d), input(i) {}
@@ -44,10 +43,29 @@ public:
     bool compiling() const;
     void compiling(bool);
 
+    /**
+     * Saves execution state so that a new execution can begin.
+     * Used for EVALUATE.
+     */
     std::pair<Addr, std::jmp_buf> save();
+
+    /**
+     * Reloads the given execution state.
+     */
     void load(const std::pair<Addr, std::jmp_buf>&);
 
+    /**
+     * Begins execution at the given execution token.
+     * If the token is a CoreWord, this function exits after its execution.
+     * Otherwise, execution continues until the word's execution completes.
+     * Encountering an error will cause this function to exit immediately.
+     */
     Error execute(Addr);
+
+    /**
+     * Clears the data and return stacks, sets ip to zero, and clears the
+     * compiling flag.
+     */
     void reset();
 
     std::size_t size() const noexcept;
@@ -65,11 +83,6 @@ public:
         return *--dsp;
     }
 
-    inline Cell beyondip() {
-        ip += sizeof(Cell);
-        return dict.read(ip);
-    }
-
     inline void pushr(Cell value) {
         if (rsp == rstack + ReturnStackSize)
             std::longjmp(jmpbuf, static_cast<int>(Error::pushr));
@@ -94,12 +107,17 @@ public:
         return *(dsp - i - 1);
     }
 
+    // Advances the instruction pointer and returns that cell's contents.
+    inline Cell beyondip() {
+        ip += sizeof(Cell);
+        return dict.read(ip);
+    }
+
 private:
     Cell dstack[DataStackSize] = {};
     Cell rstack[ReturnStackSize] = {};
     Cell *dsp = dstack;
     Cell *rsp = rstack;
-
 };
 
 #endif // ALEEFORTH_STATE_HPP
-- 
cgit v1.2.3