add doxygen support

.gitignore

@@ -8,5 +8,6 @@ alee-msp430
 alee-standalone
 libalee.a
 core.fth.h
+doc/
 msp430/lzss
 msp430/msp430fr2476_all.h

alee.hpp

@@ -1,3 +1,6 @@
+/// @file alee.hpp
+/// @brief Single header to include all of Alee Forth
+
 #include "libalee/parser.hpp"
 #include "libalee/state.hpp"
 

libalee/corewords.hpp

@@ -1,20 +1,22 @@
-/**
+//
- * Alee Forth: A portable and concise Forth implementation in modern C++.
+/// @file corewords.hpp
- * Copyright (C) 2023  Clyne Sullivan <clyne@bitgloo.com>
+/// @brief Manages the fundamental word-set and its execution.
- *
+//
- * This program is free software: you can redistribute it and/or modify
+// Alee Forth: A portable and concise Forth implementation in modern C++.
- * it under the terms of the GNU Lesser General Public License as published by
+// Copyright (C) 2023  Clyne Sullivan <clyne@bitgloo.com>
- * the Free Software Foundation, either version 3 of the License, or
+//
- * (at your option) any later version.
+// This program is free software: you can redistribute it and/or modify
- *
+// it under the terms of the GNU Lesser General Public License as published by
- * This program is distributed in the hope that it will be useful,
+// the Free Software Foundation, either version 3 of the License, or
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
+// (at your option) any later version.
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+//
- * GNU Lesser General Public License for more details.
+// This program is distributed in the hope that it will be useful,
- *
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
- * You should have received a copy of the GNU Lesser General Public License
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+// GNU Lesser General Public License for more details.
- */
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 #ifndef ALEEFORTH_COREWORDS_HPP
 #define ALEEFORTH_COREWORDS_HPP
@@ -27,29 +29,56 @@
 /**
  * To be implemented by the user, this function is called when the `sys` word
  * is executed.
+ * @param state Current execution state object.
  */
-void user_sys(State&);
+void user_sys(State& state);
 
+/**
+ * @class CoreWords
+ * @brief Provides the fundamental word-set and manages its execution.
+ */
 class CoreWords
 {
 public:
+    /**
+     * Count of total fundamental words.
+     */
     constexpr static Cell WordCount = 37;
+
+    /**
+     * Token/index of the semicolon word (";").
+     */
     constexpr static Cell Semicolon = 26;
 
     /**
-     * Finds execution token that corresponds to the given word.
+     * Searches for the token/index of the given word if it is part of the
-     * Returns -1 if not found.
+     * fundamental word-set.
+     * @param state Current execution state object.
+     * @param word Word (stored in state's dictionary memory) to look up.
+     * @return The token/index of the word or -1 if not found.
+     */
+    static Cell findi(State& state, Word word);
+
+    /**
+     * Looks up the token/index of the given fundamental word.
+     * Can evaluate at compile-time.
+     * @param word The word to look up.
+     * @return The token/index of the word or -1 if not found.
      */
-    static Cell findi(State&, Word);
     consteval static Cell findi(const char *word) {
         return findi(word, std::strlen(word));
     }
 
     /**
-     * Executes the given CoreWord execution token using the given state.
+     * Executes the given execution token using the given state.
+     * @param token Any valid execution token (word, fundamental, constant...).
+     * @param state The state object to execute with.
      */
-    static void run(Cell, State&);
+    static void run(Cell token, State& state);
 
+    /**
+     * String lookup table for the fundamental word-set.
+     */
     constexpr static char wordsarr[] =
         "_lit\0drop\0dup\0swap\0pick\0sys\0"
         "+\0-\0m*\0_/\0_%\0"
@@ -61,6 +90,12 @@ public:
         "_uma\0u<\0um/mod\0";
 
 private:
+    /**
+     * Generic implementation of findi(). Private; use public implementations.
+     * @param it Beginning iterator of the word to search for.
+     * @param size Size of the searched-for word i.e. end == it + size.
+     * @return The token/index of the word or -1 if not found.
+     */
     template<typename Iter>
     constexpr static Cell findi(Iter it, std::size_t size)
     {

libalee/ctype.hpp

@@ -1,42 +1,44 @@
-/**
+//
- * Alee Forth: A portable and concise Forth implementation in modern C++.
+/// @file ctype.hpp
- * Copyright (C) 2023  Clyne Sullivan <clyne@bitgloo.com>
+/// @brief Simple implementations of character comparison functions.
- *
+//
- * This program is free software: you can redistribute it and/or modify
+// Alee Forth: A portable and concise Forth implementation in modern C++.
- * it under the terms of the GNU Lesser General Public License as published by
+// Copyright (C) 2023  Clyne Sullivan <clyne@bitgloo.com>
- * the Free Software Foundation, either version 3 of the License, or
+//
- * (at your option) any later version.
+// This program is free software: you can redistribute it and/or modify
- *
+// it under the terms of the GNU Lesser General Public License as published by
- * This program is distributed in the hope that it will be useful,
+// the Free Software Foundation, either version 3 of the License, or
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
+// (at your option) any later version.
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+//
- * GNU Lesser General Public License for more details.
+// This program is distributed in the hope that it will be useful,
- *
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
- * You should have received a copy of the GNU Lesser General Public License
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+// GNU Lesser General Public License for more details.
- */
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 #ifndef ALEEFORTH_CTYPE_HPP
 #define ALEEFORTH_CTYPE_HPP
 
-/**
- * We implement our own character comparison functions to keep them lean.
- */
-
 #include <cstdint>
 
+/** Tests if given character represents whitespace. */
 constexpr inline bool isspace(uint8_t c) {
     return c == ' ' || c == '\t' || c == '\r' || c == '\n';
 }
 
+/** Tests if given character is a numerical digit. */
 constexpr inline bool isdigit(uint8_t c) {
     return c >= '0' && c <= '9';
 }
 
+/** Tests if given character is an uppercase letter. */
 constexpr inline bool isupper(uint8_t c) {
     return c >= 'A' && c <= 'Z';
 }
 
+/** Tests if given character is a letter. */
 constexpr inline bool isalpha(uint8_t c) {
     return isupper(c) || (c >= 'a' && c <= 'z');
 }

libalee/dictionary.hpp

@@ -1,20 +1,22 @@
-/**
+//
- * Alee Forth: A portable and concise Forth implementation in modern C++.
+/// @file dictionary.hpp
- * Copyright (C) 2023  Clyne Sullivan <clyne@bitgloo.com>
+/// @brief Defines the dictionary interface and common functionality.
- *
+//
- * This program is free software: you can redistribute it and/or modify
+// Alee Forth: A portable and concise Forth implementation in modern C++.
- * it under the terms of the GNU Lesser General Public License as published by
+// Copyright (C) 2023  Clyne Sullivan <clyne@bitgloo.com>
- * the Free Software Foundation, either version 3 of the License, or
+//
- * (at your option) any later version.
+// This program is free software: you can redistribute it and/or modify
- *
+// it under the terms of the GNU Lesser General Public License as published by
- * This program is distributed in the hope that it will be useful,
+// the Free Software Foundation, either version 3 of the License, or
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
+// (at your option) any later version.
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+//
- * GNU Lesser General Public License for more details.
+// This program is distributed in the hope that it will be useful,
- *
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
- * You should have received a copy of the GNU Lesser General Public License
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+// GNU Lesser General Public License for more details.
- */
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 #ifndef ALEEFORTH_DICTIONARY_HPP
 #define ALEEFORTH_DICTIONARY_HPP
@@ -27,103 +29,175 @@
 #include <cstdint>
 
 /**
- * Dictionary entry format:
+ * @class Dictionary
- *  - 1 information byte
+ * @brief Provides an interface and essential funcitonality for a dictionary.
- *    bits  0..4: Length of name (L)
+ * @details The core read and write functionality is left virtual so that
- *    bit      5: Immediate?
+ * dictionaries can be stored in any medium. So, this class cannot be used
- *    bits 6..15: Distance to next entry (negative)
+ * directly; the programmer must define a dictionary class that inherits this
- *  - L bytes of name
+ * one.
- *  - 0+ bytes for address alignment
+ * 
- *  - 0+ bytes of entry's data...
+ * Dictionary entry format (for a 16-bit implementation):
+ *  - One information cell:
+ *    - bits 0..4: Length of name
+ *    - bit 5: Set if word is immediate
+ *    - bits 6..15: Distance (backwards) to the next entry
+ *    - If bits 6..15 are all one-bits then distance is in the following cell.
+ *  - "Length" bytes of name
+ *  - Zero or more bytes for address alignment
+ *  - Zero or more bytes of the definition's contents
  */
-
 class Dictionary
 {
 public:
-    /**
+    /** Stores Numerical base to use for input/output. */
-     * The beginning of the dictionary is used for "internal" variables.
-     */
     constexpr static Addr Base       = 0;
+    /** Stores the current `here` address. */
     constexpr static Addr Here       = sizeof(Cell);
+    /** Stores the address of the most recently defined word. */
     constexpr static Addr Latest     = sizeof(Cell) * 2;
+    /** Stores a boolean indication of compiling state. */
     constexpr static Addr Compiling  = sizeof(Cell) * 3;
+    /** Stores the address of the last execution token determined by colon. */
     constexpr static Addr CompToken  = sizeof(Cell) * 4;
+    /** Stores the address of the current interpreter input source. */
     constexpr static Addr Source     = sizeof(Cell) * 5;
+    /** Stores the size in bytes of the interpreter input source. */
     constexpr static Addr SourceLen  = sizeof(Cell) * 6;
-    constexpr static Addr Input      = sizeof(Cell) * 7; // len data...
+    /** Stores the dictionary's input buffer (a counted string). */
-    constexpr static Addr InputCells = 80; // bytes!
+    constexpr static Addr Input      = sizeof(Cell) * 7;
+    /** Stores the size of the dictionary's input buffer in bytes. */
+    constexpr static Addr InputCells = 80;
+    /** Stores the dictionary's "beginning" i.e. where new definitions begin. */
     constexpr static Addr Begin      = sizeof(Cell) * 8 + InputCells;
 
-    constexpr static Cell Immediate = (1 << 5);
-
     /**
-     * Dictionary data can be stored on any read-write interface.
+     * The "immediate" identifier bit used in a definition's information cell.
-     * You must create a dictionary class that inherits Dictionary and
-     * implement these functions. See `memdict.hpp` for a simple block-of-
-     * memory implementation.
      */
+    constexpr static Cell Immediate = (1 << 5);
+
+    /** Returns the value of the cell at the given address. */
     virtual Cell read(Addr) const noexcept = 0;
+
+    /** Writes the given value to the cell at the given address. */
     virtual void write(Addr, Cell) noexcept = 0;
+
+    /** Returns the byte stored at the given address. */
     virtual uint8_t readbyte(Addr) const noexcept = 0;
+
+    /** Writes the given byte to the given address. */
     virtual void writebyte(Addr, uint8_t) noexcept = 0;
+
+    /** Returns the total capacity of the dictionary in bytes. */
     virtual unsigned long int capacity() const noexcept = 0;
 
     /**
-     * Does initial dictionary setup, required before use for execution.
+     * Initializes essential dictionary values.
+     * Must be called before dictionary use.
      */
     void initialize();
 
+    /**
+     * Gets the address stored in `here`.
+     */
     Addr here() const noexcept { return read(Here); }
+
+    /**
+     * Sets the address stored in `here`.
+     */
     void here(Addr l) noexcept { write(Here, l); }
 
+    /**
+     * Gets the value of `latest`.
+     */
     Addr latest() const noexcept { return read(Latest); }
+
+    /**
+     * Sets the value of `latest`.
+     */
     void latest(Addr l) noexcept { write(Latest, l); }
 
-    // Aligns the given address.
+    /**
-    static Addr aligned(Addr);
+     * Aligns the given address to the next Cell boundary if necessary.
-    // Aligns `here`.
+     * @param addr The address to align.
+     * @return The resulting aligned address.
+     */
+    static Addr aligned(Addr addr);
+
+    /**
+     * Aligns `here` to the next Cell boundary if necessary.
+     * @return The new aligned address stored in `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`.
+     * Allocates memory by returning and then increasing the current `here`.
-     * The entry does not become active until a semicolon is executed.
+     * @param count The number of bytes to increase `here` by.
+     * @return The address stored in `here` before the increase.
+     */
+    Addr allot(Cell count) noexcept;
+
+    /**
+     * Stores the given value to `here` then calls allot to "save" that cell.
+     * @param value The value to store.
+     * @see allot(Cell)
+     */
+    void add(Cell value) noexcept;
+
+    /**
+     * Stores the beginning of a new word definition in the dictionary.
+     * The word must eventually have its definition concluded via semicolon.
+     * @param word The dictionary-stored name of the new word.
      */
-    void addDefinition(Word) noexcept;
+    void addDefinition(Word word) noexcept;
 
     /**
      * Searches the dictionary for an entry for the given word.
-     * Returns zero if not found.
+     * @param word The dictionary-stored word to search for.
+     * @return The beginning address of the word or zero if not found.
      */
-    Addr find(Word) noexcept;
+    Addr find(Word word) noexcept;
 
     /**
-     * Given the address of a dictionary entry, produces the execution token
+     * Produces the execution token for the given dictionary entry.
-     * for that entry.
+     * @param addr The beginning address of a defined word.
+     * @return The execution token for the given word.
+     * @see find(Word)
      */
-    Addr getexec(Addr) noexcept;
+    Addr getexec(Addr addr) noexcept;
 
     /**
      * Reads the next word from the input buffer.
-     * Returns an empty word if the buffer is empty or entirely read.
+     * @return The next word or an empty word if one is not available.
      */
     Word input() noexcept;
+
+    /**
+     * Returns true if the dictionary's input buffer has  immediately available
+     * data.
+     */
     bool hasInput() const noexcept;
 
     /**
-     * Checks if this dictionary's word is equivalent to the given string/size.
+     * Checks if the dictionary-stored word is equivalent to the given string.
+     * @param word Dictionary-stored word to compare against.
+     * @param str String to compare to.
+     * @param size Size of the string to compare to.
+     * @return True if the two words are equivalent.
      */
-    bool equal(Word, const char *, unsigned) const noexcept;
+    bool equal(Word word, const char *str, unsigned size) const noexcept;
 
     /**
-     * Checks if two words in this dictionary's word are equivalent.
+     * Checks if two words stored in this dictionary are equivalent.
+     * @param word1 First word to compare
+     * @param word2 Second word to compare
+     * @return True if the words are equivalent.
      */
-    bool equal(Word, Word) const noexcept;
+    bool equal(Word word1, Word word2) const noexcept;
 
-    // Used for case-insensitive comparison between two iterators.
+    /**
+     * Generic equality comparison using our own case-insensitive comparator.
+     * Arguments and return value identical to std::equal.
+     */
     template<typename Iter1, typename Iter2>
     constexpr static bool equal(Iter1 b1, Iter1 e1, Iter2 b2) {
         return std::equal(b1, e1, b2, eqchars);
@@ -132,7 +206,10 @@ public:
     virtual ~Dictionary() = default;
 
 private:
-    // Case-insensitive comparison.
+    /**
+     * Case-insensitive character comparison used for dictionary lookup.
+     * @return True if the characters are equivalent.
+     */
     constexpr static bool eqchars(char c1, char c2) {
         if (isalpha(static_cast<uint8_t>(c1)))
             c1 |= 32;

libalee/parser.hpp

@@ -1,20 +1,22 @@
-/**
+//
- * Alee Forth: A portable and concise Forth implementation in modern C++.
+/// @file parser.hpp
- * Copyright (C) 2023  Clyne Sullivan <clyne@bitgloo.com>
+/// @brief Provides functions to parse text for interpretation/execution.
- *
+//
- * This program is free software: you can redistribute it and/or modify
+// Alee Forth: A portable and concise Forth implementation in modern C++.
- * it under the terms of the GNU Lesser General Public License as published by
+// Copyright (C) 2023  Clyne Sullivan <clyne@bitgloo.com>
- * the Free Software Foundation, either version 3 of the License, or
+//
- * (at your option) any later version.
+// This program is free software: you can redistribute it and/or modify
- *
+// it under the terms of the GNU Lesser General Public License as published by
- * This program is distributed in the hope that it will be useful,
+// the Free Software Foundation, either version 3 of the License, or
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
+// (at your option) any later version.
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+//
- * GNU Lesser General Public License for more details.
+// This program is distributed in the hope that it will be useful,
- *
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
- * You should have received a copy of the GNU Lesser General Public License
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+// GNU Lesser General Public License for more details.
- */
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 #ifndef ALEEFORTH_PARSER_HPP
 #define ALEEFORTH_PARSER_HPP
@@ -23,37 +25,60 @@
 
 #include <string_view>
 
+/**
+ * @class Parser
+ * @brief Provides routines for parsing Forth code.
+ */
 class Parser
 {
 public:
+    /**
+     * Pointer to a user-provided function that
+     */
     static Error (*customParse)(State&, Word);
 
     /**
-     * Parses (and evaluates) the given string using the given state.
+     * Parses and evaluates the given string using the given state.
-     * The string is stored in the state's input buffer, then parseSource()
+     * The string is stored in the state's input buffer before parseSource()
-     * works through that using parseWord(). parseWord() will compile or
+     * is called.
-     * execute as necessary.
+     * @param state The state to parse and evaluate with.
+     * @param str The string to parse.
+     * @return Error token to indicate if parsing was successful.
+     * @see parseSource(State&)
      */
-    static Error parse(State&, const char *);
+    static Error parse(State& state, const char *str);
 
     /**
-     * Parses (and evaluates) through the words stored in the state's input
+     * Parses through and compiles or evaluates the words stored in the state's
-     * buffer.
+     * input source.
+     * @param state The state to parse with.
+     * @return Error token to indicate if parsing was successful.
+     * @see parseWord(State&, Word)
      */
-    static Error parseSource(State&);
+    static Error parseSource(State& state);
 
-    static void processLiteral(State&, Cell);
+    /**
+     * Parses the given value and either pushes it to the stack or compiles
+     * that functionality.
+     * @param state The state to give the value to.
+     * @param value The value to process.
+     */
+    static void processLiteral(State& state, Cell value);
 
 private:
     /**
      * Parses the given word using the given state.
+     * @return Error token to indicate if parsing was successful.
      */
     static Error parseWord(State&, Word);
 
     /**
      * Attempts to parse the given word into a number.
+     * @param state The state object with the dictionary containing the word.
+     * @param word The dictionary-stored word (number) to parse.
+     * @return Error token to indicate if parsing was successful.
      */
-    static Error parseNumber(State&, Word);
+    static Error parseNumber(State& state, Word word);
 };
 
 #endif // ALEEFORTH_PARSER_HPP

libalee/state.hpp

@@ -1,20 +1,22 @@
-/**
+//
- * Alee Forth: A portable and concise Forth implementation in modern C++.
+/// @file state.hpp
- * Copyright (C) 2023  Clyne Sullivan <clyne@bitgloo.com>
+/// @brief Provides object to manage execution and interpretation state.
- *
+//
- * This program is free software: you can redistribute it and/or modify
+// Alee Forth: A portable and concise Forth implementation in modern C++.
- * it under the terms of the GNU Lesser General Public License as published by
+// Copyright (C) 2023  Clyne Sullivan <clyne@bitgloo.com>
- * the Free Software Foundation, either version 3 of the License, or
+//
- * (at your option) any later version.
+// This program is free software: you can redistribute it and/or modify
- *
+// it under the terms of the GNU Lesser General Public License as published by
- * This program is distributed in the hope that it will be useful,
+// the Free Software Foundation, either version 3 of the License, or
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
+// (at your option) any later version.
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+//
- * GNU Lesser General Public License for more details.
+// This program is distributed in the hope that it will be useful,
- *
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
- * You should have received a copy of the GNU Lesser General Public License
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+// GNU Lesser General Public License for more details.
- */
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 #ifndef ALEEFORTH_STATE_HPP
 #define ALEEFORTH_STATE_HPP
@@ -25,31 +27,53 @@
 #include <csetjmp>
 #include <cstddef>
 
+/**
+ * Size of the primary data stack, number of cells.
+ */
 constexpr unsigned DataStackSize = 64;
+
+/**
+ * Size of the return stack, number of cells.
+ */
 constexpr unsigned ReturnStackSize = 64;
 
+/**
+ * @class State
+ * Object to track execution state.
+ */
 class State
 {
+    /** Input functions should add input to the input buffer when available. */
     using InputFunc = void (*)(State&);
 
+    /** Context object that defines a state of execution. */
     struct Context {
-        Addr ip = 0;
+        Addr ip = 0; /** Instruction pointer */
-        std::jmp_buf jmpbuf = {};
+        std::jmp_buf jmpbuf = {}; /** setjmp() buffer for exiting execute() */
     };
 
 public:
+    /** Reference to dictionary used by this state. */
     Dictionary& dict;
 
+    /**
+     * Constructs a state object that uses the given dictionary and input
+     * function.
+     * @param d The dictionary to be used by this state
+     * @param i The input collection function to be used by this state
+     */
     constexpr State(Dictionary& d, InputFunc i):
         dict(d), inputfunc(i), context() {}
 
     /**
-     * Begins execution at the given execution token.
+     * Begins execution starting from 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.
+     * @param addr The token to be executed
+     * @return An error token to indicate if execution was successful
      */
-    Error execute(Addr);
+    Error execute(Addr addr);
 
     /**
      * Clears the data and return stacks, sets ip to zero, and clears the
@@ -57,23 +81,28 @@ public:
      */
     void reset();
 
+    /** Returns a reference to the instruction pointer. */
     Addr& ip() noexcept {
         return context.ip;
     }
 
+    /** Calls the user input function with this state as the argument. */
     void input() noexcept {
         inputfunc(*this);
     }
 
+    /** Returns true if currently in a compiling state. */
     bool compiling() const;
+    /** Sets the compiling state. True if compiling, false if interpreting. */
     void compiling(bool);
 
+    /** Returns the number of values stored on the data stack. */
     std::size_t size() const noexcept;
+    /** Returns the number of values stored on the return stack. */
     std::size_t rsize() const noexcept;
 
     /**
-     * Saves execution state so that a new execution can begin.
+     * Returns the current execution state. Usually followed by a load() call.
-     * Used for EVALUATE.
      */
     Context save();
 
@@ -82,55 +111,83 @@ public:
      */
     void load(const Context&);
 
+    /**
+     * Pushes the given value to the data stack.
+     */
     inline void push(Cell value) {
         verify(dsp < dstack + DataStackSize, Error::push);
         *dsp++ = value;
     }
 
+    /**
+     * Pops a value from the data stack and returns that value.
+     */
     inline Cell pop() {
         verify(dsp > dstack, Error::pop);
         return *--dsp;
     }
 
+    /**
+     * Pushes the given value to the return stack.
+     */
     inline void pushr(Cell value) {
         verify(rsp < rstack + ReturnStackSize, Error::pushr);
         *rsp++ = value;
     }
 
+    /**
+     * Pops a value from the return stack and returns that value.
+     */
     inline Cell popr() {
         verify(rsp > rstack, Error::popr);
         return *--rsp;
     }
 
+    /**
+     * Returns the value stored at the current data stack position.
+     */
     inline Cell& top() {
         verify(dsp > dstack, Error::top);
         return *(dsp - 1);
     }
 
+    /**
+     * Picks a value currently stored on the data stack.
+     * @param i Index from current position to fetch from
+     * @return The value stored at the given index
+     */
     inline Cell& pick(std::size_t i) {
         verify(dsp - i > dstack, Error::pick);
         return *(dsp - i - 1);
     }
 
-    // Advances the instruction pointer and returns that cell's contents.
+    /**
+     * Advances the instruction pointer and returns that cell's contents.
+     */
     inline Cell beyondip() {
         context.ip += sizeof(Cell);
         return dict.read(context.ip);
     }
 
+    /**
+     * Asserts the given condition is true, longjmp-ing if false.
+     * Used as an exception handler and the method of exiting execution.
+     * @param condition Condition to be tested
+     * @param error Error code to report via longjmp() on false condition
+     */
     inline void verify(bool condition, Error error) {
         if (!condition)
             std::longjmp(context.jmpbuf, static_cast<int>(error));
     }
 
 private:
-    InputFunc inputfunc; // User-provided function to collect "stdin" input.
+    InputFunc inputfunc; /** User-provided function to collect user input. */
-    Context context;
+    Context context; /** State's current execution context. */
 
-    Cell dstack[DataStackSize] = {};
+    Cell dstack[DataStackSize] = {}; /** Data stack */
-    Cell rstack[ReturnStackSize] = {};
+    Cell rstack[ReturnStackSize] = {}; /** Return stack */
-    Cell *dsp = dstack;
+    Cell *dsp = dstack; /** Current data stack position */
-    Cell *rsp = rstack;
+    Cell *rsp = rstack; /** Current return stack position */
 };
 
 #endif // ALEEFORTH_STATE_HPP

libalee/types.hpp

@@ -1,20 +1,22 @@
-/**
+//
- * Alee Forth: A portable and concise Forth implementation in modern C++.
+/// @file types.hpp
- * Copyright (C) 2023  Clyne Sullivan <clyne@bitgloo.com>
+/// @brief Defines common types used throughout Alee Forth.
- *
+//
- * This program is free software: you can redistribute it and/or modify
+// Alee Forth: A portable and concise Forth implementation in modern C++.
- * it under the terms of the GNU Lesser General Public License as published by
+// Copyright (C) 2023  Clyne Sullivan <clyne@bitgloo.com>
- * the Free Software Foundation, either version 3 of the License, or
+//
- * (at your option) any later version.
+// This program is free software: you can redistribute it and/or modify
- *
+// it under the terms of the GNU Lesser General Public License as published by
- * This program is distributed in the hope that it will be useful,
+// the Free Software Foundation, either version 3 of the License, or
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
+// (at your option) any later version.
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+//
- * GNU Lesser General Public License for more details.
+// This program is distributed in the hope that it will be useful,
- *
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
- * You should have received a copy of the GNU Lesser General Public License
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+// GNU Lesser General Public License for more details.
- */
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 #ifndef ALEEFORTH_TYPES_HPP
 #define ALEEFORTH_TYPES_HPP
@@ -22,54 +24,85 @@
 #include <cstdint>
 #include <iterator>
 
-/**
+/** Dictionary address type. Must be equivalent to "unsigned Cell". */
- * Configure the below types for your platform.
- */
 using Addr = uint16_t;
+/** Data cell type. Dictionary is basically an array of this type. */
 using Cell = int16_t;
+/** Double-width cell type. Must be twice the size of Cell. */
 using DoubleCell = int32_t;
-using DoubleAddr = uint32_t; // Only used for um/mod.
+/** Double-width addr type. Must be twice the size of Addr. Used by um/mod. */
+using DoubleAddr = uint32_t;
 
 struct Dictionary;
 struct State;
 
-using Func = void (*)(State&);
+/**
-
+ * Error enum to report success or failure of parsing or execution.
+ */
 enum class Error : int {
-    none = 0,
+    none = 0, /** No error */
-    push,
+    push,  /** Could not push (data stack overflow) */
-    pop,
+    pop,   /** Could not pop (data stack underflow) */
-    pushr,
+    pushr, /** Could not push (return stack overflow) */
-    popr,
+    popr,  /** Could not pop (return stack underflow) */
-    top,
+    top,   /** Could not fetch data stack top (data stack underflow) */
-    pick,
+    pick,  /** Could not pick data stack value (data stack underflow) */
-    exit,
+    exit,  /** No error, exited from State::execute() */
-    noword
+    noword /** Parsing failed because the word was not found */
 };
 
 /**
- * Stores the start and past-the-end addresses of a dictionary's word.
+ * @class Word
+ * Stores the beginning and end indices of a dictionary-defined word.
  */
 class Word
 {
+    /** Beginning (inclusive) index */
     Addr start;
+    /** End (exclusive) index */
     Addr wend;
 
 public:
     struct iterator;
 
+    /**
+     * Constructs a word with the given start and end indices.
+     * @param s Start/beginning index
+     * @param e (past-the-)end index
+     */
     constexpr explicit Word(Addr s = 0, Addr e = 0):
         start(s), wend(e) {}
 
+    /**
+     * Constructs a word using beginning index and length.
+     * @param s Beginning/start index of word
+     * @param l Count of bytes until end of word
+     * @return Resulting Word object
+     */
     static constexpr Word fromLength(Addr s, Addr l) {
         return Word(s, s + l);
     }
 
+    /** Returns the size of this word in bytes. */
     Addr size() const noexcept;
 
-    iterator begin(const Dictionary *);
+    /**
-    iterator end(const Dictionary *);
+     * Creates a beginning iterator for the word.
+     * @param dict Pointer to dictionary object containing this word
+     * @return Iterator pointing to this word's beginning
+     */
+    iterator begin(const Dictionary *dict);
+
+    /**
+     * Creates an end iterator for the word.
+     * @param dict Pointer to dictionary object containing this word
+     * @return Iterator pointing to past-the-end of this word
+     */
+    iterator end(const Dictionary *dict);
 
+    /**
+     * Forward-iterator for iterating through the letters of this word.
+     */
     struct iterator {
         using iterator_category = std::input_iterator_tag;
         using value_type = uint8_t;
@@ -77,15 +110,26 @@ public:
         using reference = void;
         using difference_type = Cell;
 
+        /** Iterator's current address within its containing dictionary. */
         Addr addr;
+        /** Pointer to dictionary that contains this word. */
         const Dictionary *dict;
 
+        /**
+         * Constructs a word iterator.
+         * @param a The address the iterator points to
+         * @param d The dictionary that contains this word
+         */
         constexpr iterator(Addr a, const Dictionary *d):
             addr(a), dict(d) {}
 
+        /** Prefix increment */
         iterator& operator++();
+        /** Postfix increment */
         iterator operator++(int);
+        /** Returns value pointed to by iterator */
         value_type operator*();
+        /** Iterator comparison function (case-insensitive) */
         bool operator!=(const iterator&);
     };
 };

memdict.hpp

@@ -1,20 +1,22 @@
-/**
+//
- * Alee Forth: A portable and concise Forth implementation in modern C++.
+/// @file memdict.hpp
- * Copyright (C) 2023  Clyne Sullivan <clyne@bitgloo.com>
+/// @brief Simple dictionary implementation using a large memory block.
- *
+//
- * This program is free software: you can redistribute it and/or modify
+// Alee Forth: A portable and concise Forth implementation in modern C++.
- * it under the terms of the GNU Lesser General Public License as published by
+// Copyright (C) 2023  Clyne Sullivan <clyne@bitgloo.com>
- * the Free Software Foundation, either version 3 of the License, or
+//
- * (at your option) any later version.
+// This program is free software: you can redistribute it and/or modify
- *
+// it under the terms of the GNU Lesser General Public License as published by
- * This program is distributed in the hope that it will be useful,
+// the Free Software Foundation, either version 3 of the License, or
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
+// (at your option) any later version.
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+//
- * GNU Lesser General Public License for more details.
+// This program is distributed in the hope that it will be useful,
- *
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
- * You should have received a copy of the GNU Lesser General Public License
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+// GNU Lesser General Public License for more details.
- */
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 #ifndef ALEEFORTH_MEMDICT_HPP
 #define ALEEFORTH_MEMDICT_HPP
@@ -22,31 +24,44 @@
 #include "alee.hpp"
 
 #ifndef MEMDICTSIZE
+/** Default dictionary size in bytes. */
 #define MEMDICTSIZE (65536)
 #endif
+
+/** Size in bytes of a MemDict. */
 constexpr unsigned long int MemDictSize = MEMDICTSIZE;
 
+/**
+ * @class MemDict
+ * Dictionary implementation that uses a large block of memory.
+ */
 class MemDict : public Dictionary
 {
+    /** Block of memory to contain dictionary's contents. */
     uint8_t dict[MemDictSize] = {0};
 
 public:
+    /** Returns the value of the cell at the given address. */
     virtual Cell read(Addr addr) const noexcept final {
         return *reinterpret_cast<const Cell *>(dict + addr);
     }
 
+    /** Writes the given value to the cell at the given address. */
     virtual void write(Addr addr, Cell value) noexcept final {
         *reinterpret_cast<Cell *>(dict + addr) = value;
     }
 
+    /** Returns the value of the byte at the given address. */
     virtual uint8_t readbyte(Addr addr) const noexcept final {
         return dict[addr];
     }
 
+    /** Writes the given value to the byte at the given address. */
     virtual void writebyte(Addr addr, uint8_t value) noexcept final {
         dict[addr] = value;
     }
 
+    /** Returns the size of the dictionary's memory block. */
     virtual unsigned long int capacity() const noexcept final {
         return sizeof(dict);
     }