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++.
- * Copyright (C) 2023  Clyne Sullivan <[email protected]>
- *
- * 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
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * 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/>.
- */
+//
+/// @file corewords.hpp
+/// @brief Manages the fundamental word-set and its execution.
+//
+// Alee Forth: A portable and concise Forth implementation in modern C++.
+// Copyright (C) 2023  Clyne Sullivan <[email protected]>
+//
+// 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
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// 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.
-     * Returns -1 if not found.
+     * Searches for the token/index of the given word if it is part of the
+     * 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 @@ class CoreWords
         "_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++.
- * Copyright (C) 2023  Clyne Sullivan <[email protected]>
- *
- * 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
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * 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/>.
- */
+//
+/// @file ctype.hpp
+/// @brief Simple implementations of character comparison functions.
+//
+// Alee Forth: A portable and concise Forth implementation in modern C++.
+// Copyright (C) 2023  Clyne Sullivan <[email protected]>
+//
+// 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
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// 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');
 }