1 files changed, 35 insertions, 8 deletions
diff --git a/source/types.hpp b/source/types.hpp
index 03e9f2a..461d835 100644
--- a/source/types.hpp
+++ b/source/types.hpp
@@ -22,19 +22,29 @@
 #include <cstddef>
 #include <cstdint>
 
-using Cell = intptr_t;
-using Addr = uintptr_t;
-using Func = void (*)();
-using FuncList = Func const *;
+using Cell = intptr_t;   /** Type of a dictionary's cell. */
+using Addr = uintptr_t;  /** Type of a dictionary address. */
+using Func = void (*)(); /** Words are built of these types of functions. */
+using FuncList = Func const *; /** Words are defined as a list of Func. */
+
+// Cells, Addrs, and Funcs must all be the same size in bytes since the
+// dictionary stores all of these types of values.
 
 static_assert(sizeof(Cell) == sizeof(Addr));
 static_assert(sizeof(Cell) == sizeof(Func));
 
+/**
+ * @struct Word
+ * @brief Structure of a word's definition.
+ * A word has a name, a body (list of functions), a link to the next word
+ * definition, and an immediate indicator. This structure is matched when
+ * words are defined in the dictionary by ":" and ";".
+ */
 struct Word {
-    FuncList list;
-    const char *name;
-    Word *link = nullptr;
-    Cell imm = 0;
+    FuncList list;        /** The word's body/definition. */
+    const char *name;     /** Null-terminated string of word's name. */
+    Word *link = nullptr; /** Link to next word in definition chain. */
+    Cell imm = 0;         /** If non-zero, word is "immediate". */
 
     constexpr Word(const char *n, FuncList l):
         list(l), name(n) {}
@@ -49,18 +59,31 @@ struct Word {
     }
 };
 
+// Words are built in the dictionary by the user using ":". These assertions
+// ensure that the structures created by ":" match the actual structure of a
+// Word exactly.
+
 static_assert(offsetof(Word, list) == 0);
 static_assert(offsetof(Word, name) == 1 * sizeof(Cell));
 static_assert(offsetof(Word, link) == 2 * sizeof(Cell));
 static_assert(offsetof(Word, imm)  == 3 * sizeof(Cell));
 static_assert(sizeof(Word)         == 4 * sizeof(Cell));
 
+/**
+ * @struct WordSet
+ * @brief Groups a set of pre-defined words and links them.
+ */
 template<typename... Words>
 struct WordSet
 {
     std::array<Word, sizeof...(Words)> words;
     Word *latest;
 
+    /**
+     * Stores the given pre-defined words into the `words` array and links
+     * their definitions together. The resulting `latest` value can be used
+     * to set the global LATEST.
+     */
     constexpr WordSet(Words... ws):
         words {ws...}
     {
@@ -72,6 +95,10 @@ struct WordSet
     }
 };
 
+/**
+ * Wraps the given functions so that a function pointer list can be created
+ * and used for a word's definition.
+ */
 template<auto... funcs>
 auto WordWrap = [] {
     constexpr static Func list[1] = {