update documentation

1 files changed, 52 insertions, 6 deletions

diff --git a/libalee/dictionary.hpp b/libalee/dictionary.hpp
index 53172d2..02fb1cc 100644
--- a/libalee/dictionary.hpp
+++ b/libalee/dictionary.hpp
@@ -39,6 +39,9 @@
 class Dictionary
 {
 public:
+    /**
+     * The beginning of the dictionary is used for "internal" variables.
+     */
     constexpr static Addr Base       = 0;
     constexpr static Addr Here       = sizeof(Cell);
     constexpr static Addr Latest     = sizeof(Cell) * 2;
@@ -49,6 +52,22 @@ public:
     constexpr static Addr InputCells = 80; // bytes!
     constexpr static Addr Begin      = sizeof(Cell) * 7 + InputCells;
 
+    constexpr static Cell Immediate = (1 << 5);
+
+    /**
+     * Dictionary data can be stored on any read-write interface.
+     * You must create a dictionary class that inherits Dictionary and
+     * implement these functions. See `memdict.hpp` for a simple block-of-
+     * memory implementation.
+     */
+    virtual Cell read(Addr) const noexcept = 0;
+    virtual void write(Addr, Cell) noexcept = 0;
+    virtual uint8_t readbyte(Addr) const noexcept = 0;
+    virtual void writebyte(Addr, uint8_t) noexcept = 0;
+
+    /**
+     * Does initial dictionary setup, required before use for execution.
+     */
     void initialize();
 
     Addr here() const noexcept { return read(Here); }
@@ -57,24 +76,50 @@ public:
     Addr latest() const noexcept { return read(Latest); }
     void latest(Addr l) noexcept { write(Latest, l); }
 
-    virtual Cell read(Addr) const noexcept = 0;
-    virtual void write(Addr, Cell) noexcept = 0;
-    virtual uint8_t readbyte(Addr) const noexcept = 0;
-    virtual void writebyte(Addr, uint8_t) noexcept = 0;
-
-    Addr alignhere() noexcept;
+    // Aligns the given address.
     Addr aligned(Addr) const noexcept;
+    // Aligns `here`.
+    Addr alignhere() noexcept;
+    // Advances `here` by the given number of bytes.
     Addr allot(Cell) noexcept;
+    // Stores value to `here`, then adds sizeof(Cell) to `here`.
     void add(Cell) noexcept;
+
+    /**
+     * Uses add() to store a new definition entry starting at `here`.
+     * The entry does not become active until a semicolon is executed.
+     */
     void addDefinition(Word) noexcept;
 
+    /**
+     * Searches the dictionary for an entry for the given word.
+     * Returns zero if not found.
+     */
     Addr find(Word) noexcept;
+
+    /**
+     * Given the address of a dictionary entry, produces the execution token
+     * for that entry.
+     */
     Addr getexec(Addr) noexcept;
+
+    /**
+     * Reads the next word from the input buffer.
+     * Returns an empty word if the buffer is empty or entirely read.
+     */
     Word input() noexcept;
 
+    /**
+     * Checks if this dictionary's word is equivalent to the given string/size.
+     */
     bool equal(Word, const char *, unsigned) const noexcept;
+
+    /**
+     * Checks if two words in this dictionary's word are equivalent.
+     */
     bool equal(Word, Word) const noexcept;
 
+    // Used for case-insensitive comparison between two iterators.
     template<typename Iter1, typename Iter2>
     static bool equal(Iter1 b1, Iter1 e1, Iter2 b2) {
         return std::equal(b1, e1, b2, eqchars);
@@ -83,6 +128,7 @@ public:
     virtual ~Dictionary() = default;
 
 private:
+    // Case-insensitive comparison.
     static bool eqchars(char c1, char c2);
 };