More comments, some parts via Claude 3.7

include/ast/NodeValue.h

@@ -102,7 +102,7 @@ public:
     auto& get_variant() const { return value; }
 
 private:
-    std::variant<int, double, bool, char, String, None> value;
+    std::variant<int, double, bool, char, String, None> value; ///< The stored value
 };
 
 template <typename Op> NodeValue numeric_op(const NodeValue& lhs, const NodeValue& rhs, Op op);

include/ast/UnaryOpNode.h

 /**
- * @file BinaryOpNode.h
+ * @file UnaryOpNode.h
  * @brief Defines the UnaryOpNode class for representing unary operations in the Funk AST.
  */
 #pragma once

include/parser/Parser.h

+/**
+ * @file Parser.h
+ * @brief Definition of the Parser class for syntactic analysis in the Funk language
+ * This file defines the Parser class which performs syntactic analysis on
+ * a stream of tokens, converting them into an Abstract Syntax Tree (AST).
+ */
 #pragma once
 
 #include "lexer/Lexer.h"
@@ -11,42 +17,165 @@
 
 namespace funk
 {
+/**
+ * @brief Class responsible for syntactic analysis in the Funk language
+ * The Parser analyzes a stream of tokens according to the grammar rules
+ * of the Funk language and builds an Abstract Syntax Tree (AST) that
+ * represents the structure and semantics of the program.
+ */
 class Parser
 {
 public:
+    /**
+     * @brief Constructs a parser for the given token stream
+     * @param tokens The tokens to parse
+     * @param filename The name of the file being processed (for error reporting)
+     */
     Parser(const Vector<Token>& tokens, const String& filename);
+
+    /**
+     * @brief Destructor for the Parser class
+     */
     ~Parser();
+
+    /**
+     * @brief Parses the token stream and returns the root AST node
+     * @return Node* The root node of the parsed AST
+     */
     Node* parse();
 
+    /**
+     * @brief Creates a parser from a file
+     * @param filename The path to the file to parse
+     * @return Parser A parser initialized with tokens from the file
+     */
     static Parser load(String filename);
 
 private:
-    Vector<Token> tokens;
-    String filename;
-    int index{0};
+    Vector<Token> tokens; ///< The token stream to parse
+    String filename;      ///< The name of the source file
+    int index{0};         ///< Current index in the token stream
 
+    /**
+     * @brief Advances the index and returns the token at the new index
+     * @return Token The next token
+     */
     Token next();
+
+    /**
+     * @brief Returns the token at the current index without advancing
+     * @return Token The current token
+     */
     Token peek() const;
+
+    /**
+     * @brief Returns the token at the next index without advancing
+     * @return Token The next token
+     */
     Token peek_next() const;
+
+    /**
+     * @brief Returns the token at the previous index
+     * @return Token The previous token
+     */
     Token peek_prev() const;
 
+    /**
+     * @brief Checks if the end of the token stream has been reached
+     * @return bool True if the parser has reached the end of the tokens
+     */
     bool done() const;
+
+    /**
+     * @brief Checks if the current token is of the expected type
+     * @param type The token type to check for
+     * @return bool True if the current token matches the expected type
+     */
     bool check(TokenType type) const;
+
+    /**
+     * @brief Checks if the current token matches the expected type, and advances if it does
+     * @param expected The token type to check for
+     * @return bool True if the current token matched and the index was advanced
+     */
     bool match(TokenType expected);
 
+    /**
+     * @brief Parses a statement
+     * @return Node* The AST node representing the statement
+     */
     Node* parse_statement();
+
+    /**
+     * @brief Parses an expression
+     * @return Node* The AST node representing the expression
+     */
     Node* parse_expression();
+
+    /**
+     * @brief Parses an assignment expression
+     * @return Node* The AST node representing the assignment
+     */
     Node* parse_assignment();
 
+    /**
+     * @brief Parses a logical OR expression
+     * @return Node* The AST node representing the logical OR expression
+     */
     Node* parse_logical_or();
+
+    /**
+     * @brief Parses a logical AND expression
+     * @return Node* The AST node representing the logical AND expression
+     */
     Node* parse_logical_and();
+
+    /**
+     * @brief Parses an equality expression
+     * @return Node* The AST node representing the equality expression
+     */
     Node* parse_equality();
+
+    /**
+     * @brief Parses a comparison expression
+     * @return Node* The AST node representing the comparison expression
+     */
     Node* parse_comparison();
+
+    /**
+     * @brief Parses an additive expression
+     * @return Node* The AST node representing the additive expression
+     */
     Node* parse_additive();
+
+    /**
+     * @brief Parses a multiplicative expression
+     * @return Node* The AST node representing the multiplicative expression
+     */
     Node* parse_multiplicative();
+
+    /**
+     * @brief Parses a unary expression
+     * @return Node* The AST node representing the unary expression
+     */
     Node* parse_unary();
+
+    /**
+     * @brief Parses a factor expression
+     * @return Node* The AST node representing the factor expression
+     */
     Node* parse_factor();
+
+    /**
+     * @brief Parses a literal value
+     * @return Node* The AST node representing the literal value
+     */
     Node* parse_literal();
+
+    /**
+     * @brief Parses an identifier
+     * @return Node* The AST node representing the identifier
+     */
     Node* parse_identifier();
 };
 } // namespace funk

include/utils/Exception.h

@@ -56,6 +56,10 @@ public:
      * @param message Description of the error
      */
     LexerError(const SourceLocation& loc, const String& message) : FunkError(loc, "Lexer error", message) {}
+    /**
+     * @brief Constructs a LexerError with a message.
+     * @param message Description of the error
+     */
     LexerError(const String& message) : FunkError(SourceLocation{"", 0, 0}, "Lexer error", message) {}
 };
 
@@ -72,6 +76,10 @@ public:
      * @param message Description of the error
      */
     SyntaxError(const SourceLocation& loc, const String& message) : FunkError(loc, "Syntax error", message) {}
+    /**
+     * @brief Constructs a SyntaxError with a message.
+     * @param message Description of the error
+     */
     SyntaxError(const String& message) : FunkError(SourceLocation{"", 0, 0}, "Syntax error", message) {}
 };
 
@@ -88,6 +96,10 @@ public:
      * @param message Description of the error
      */
     TypeError(const SourceLocation& loc, const String& message) : FunkError(loc, "Type error", message) {}
+    /**
+     * @brief Constructs a TypeError with a message.
+     * @param message Description of the error
+     */
     TypeError(const String& message) : FunkError(SourceLocation{"", 0, 0}, "Type error", message) {}
 };
 
@@ -104,6 +116,10 @@ public:
      * @param message Description of the error
      */
     RuntimeError(const SourceLocation& loc, const String& message) : FunkError(loc, "Runtime error", message) {}
+    /**
+     * @brief Constructs a RuntimeError with a message.
+     * @param message Description of the error
+     */
     RuntimeError(const String& message) : FunkError(SourceLocation{"", 0, 0}, "Runtime error", message) {}
 };
 

source/main.cc

+/**
+ * @file main.cc
+ * @brief Main entry point for the Funk language interpreter
+ * This file contains the main function and supporting code for the Funk
+ * language interpreter, handling command-line arguments, file processing,
+ * and from lexing to evaluation.
+ */
+
 #include "logging/LogMacros.h"
 #include "parser/Parser.h"
 #include "utils/ArgParser.h"
@@ -5,7 +13,10 @@
 
 using namespace funk;
 
-// Command line options
+/**
+ * @brief Available command line options with descriptions
+ * Maps option flags to their help text descriptions
+ */
 HashMap<String, String> options{
     {"--help", "Display this help message"},
     {"--log <file>", "Set the log file"},
@@ -14,15 +25,23 @@ HashMap<String, String> options{
     {"--tokens", "Log the lexical tokens"},
 };
 
-// Configuration for command line options
+/**
+ * @brief Runtime configuration based on command line options
+ * Stores boolean flags for various runtime behaviors
+ */
 struct Config
 {
-    bool debug{false};
-    bool ast{false};
-    bool tokens{false};
+    bool debug{false};  ///< Enable debug level logging
+    bool ast{false};    ///< Print AST representation
+    bool tokens{false}; ///< Print lexical tokens
 };
 
-// Process command line arguments and set up logging
+/**
+ * @brief Process command line arguments and configure the interpreter
+ * @param parser The argument parser containing command line options
+ * @param config The configuration to populate
+ * @return bool True if setup was successful, false otherwise
+ */
 bool setup(ArgParser& parser, Config& config)
 {
     // Print help message
@@ -64,7 +83,12 @@ bool setup(ArgParser& parser, Config& config)
     return true;
 }
 
-// Process a single file
+/**
+ * @brief Process a single Funk source file
+ * Handles the complete execution pipeline: lexing, parsing, and evaluation
+ * @param file Path to the source file
+ * @param config Runtime configuration options
+ */
 void process_file(const String& file, const Config& config)
 {
     LOG_INFO("Processing file: " + file);
@@ -101,6 +125,13 @@ void process_file(const String& file, const Config& config)
     }
 }
 
+/**
+ * @brief Main entry point for the Funk interpreter
+ * Parses command line arguments and processes input files
+ * @param argc Number of command line arguments
+ * @param argv Array of command line argument strings
+ * @return int Exit code (0 for success, non-zero for errors)
+ */
 int main(int argc, char* argv[])
 {
     ArgParser parser(argc, argv);