Improved doxygen docs

9 files changed, 148 insertions, 77 deletions

diff --git a/src/analysis/typecheck.h b/src/analysis/typecheck.h
index fe51c4d..b690f1d 100644
--- a/src/analysis/typecheck.h
+++ b/src/analysis/typecheck.h
@@ -7,17 +7,30 @@
 // Type Checker Context
 // Holds the state during the semantic analysis pass.
 // Unlike the parser, this focuses on semantic validity (types, definitions).
+/**
+ * @brief Type Checker Context.
+ * 
+ * Holds the state during the semantic analysis pass.
+ * Unlike the parser, this focuses on semantic validity (types, definitions, correctness).
+ */
 typedef struct TypeChecker
 {
-    ParserContext *pctx;   // Reference to global parser context (for lookups)
-    Scope *current_scope;  // Current lexical scope
-    ASTNode *current_func; // Current function being checked (for return type checks)
-    int error_count;       // Number of errors found
-    int warning_count;     // Number of recommendations/warnings
+    ParserContext *pctx;   ///< Reference to global parser context (for lookups).
+    Scope *current_scope;  ///< Current lexical scope during traversal.
+    ASTNode *current_func; ///< Current function being checked (for return type checks).
+    int error_count;       ///< Number of type errors found.
+    int warning_count;     // Number of recommendations/warnings.
 } TypeChecker;
 
-// Main Entry Point
-// Returns 0 on success (no errors), non-zero if errors occurred.
+/**
+ * @brief Main Type Checking Entry Point.
+ * 
+ * Performs semantic analysis on the entire AST.
+ * 
+ * @param ctx Global parser context.
+ * @param root Root AST node of the program.
+ * @return 0 on success (no errors), non-zero if errors occurred.
+ */
 int check_program(ParserContext *ctx, ASTNode *root);
 
 #endif // TYPECHECK_H
diff --git a/src/codegen/compat.h b/src/codegen/compat.h
index 423b1d9..f34d612 100644
--- a/src/codegen/compat.h
+++ b/src/codegen/compat.h
@@ -4,20 +4,20 @@
 
 #ifdef __cplusplus
 /* C++ mode */
-#define ZC_AUTO auto
-#define ZC_CAST(T, x) static_cast<T>(x)
-#define ZC_REINTERPRET(T, x) reinterpret_cast<T>(x)
-#define ZC_EXTERN_C extern "C"
+#define ZC_AUTO auto                                ///< Auto type inference.
+#define ZC_CAST(T, x) static_cast<T>(x)             ///< Static cast.
+#define ZC_REINTERPRET(T, x) reinterpret_cast<T>(x) ///< Reinterpret cast.
+#define ZC_EXTERN_C extern "C"                      ///< Extern "C" linkage.
 #define ZC_EXTERN_C_BEGIN                                                                          \
     extern "C"                                                                                     \
     {
 #define ZC_EXTERN_C_END }
 #else
 /* C mode */
-#define ZC_AUTO __auto_type
-#define ZC_CAST(T, x) ((T)(x))
-#define ZC_REINTERPRET(T, x) ((T)(x))
-#define ZC_EXTERN_C
+#define ZC_AUTO __auto_type                         ///< Auto type inference.
+#define ZC_CAST(T, x) ((T)(x))                      ///< Explicit cast.
+#define ZC_REINTERPRET(T, x) ((T)(x))               ///< Reinterpret cast.
+#define ZC_EXTERN_C                                 ///< Extern "C" (no-op in C).
 #define ZC_EXTERN_C_BEGIN
 #define ZC_EXTERN_C_END
 #endif
diff --git a/src/constants.h b/src/constants.h
index 15bb19f..a867bf3 100644
--- a/src/constants.h
+++ b/src/constants.h
@@ -3,44 +3,54 @@
 #define ZEN_CONSTANTS_H
 
 // Buffer sizes
-#define MAX_TYPE_NAME_LEN 256
-#define MAX_FUNC_NAME_LEN 512
-#define MAX_ERROR_MSG_LEN 1024
-#define MAX_MANGLED_NAME_LEN 512
-#define MAX_PATH_LEN 4096
+// Buffer sizes
+#define MAX_TYPE_NAME_LEN 256     ///< Max length for type name strings.
+#define MAX_FUNC_NAME_LEN 512     ///< Max length for function names.
+#define MAX_ERROR_MSG_LEN 1024    ///< Max length for error messages.
+#define MAX_MANGLED_NAME_LEN 512  ///< Max length for mangled names (generics).
+#define MAX_PATH_LEN 4096         ///< Max length for file paths.
 
 // Type checking helpers
-#define IS_INT_TYPE(t) ((t) && strcmp((t), "int") == 0)
-#define IS_BOOL_TYPE(t) ((t) && strcmp((t), "bool") == 0)
-#define IS_CHAR_TYPE(t) ((t) && strcmp((t), "char") == 0)
-#define IS_VOID_TYPE(t) ((t) && strcmp((t), "void") == 0)
-#define IS_FLOAT_TYPE(t) ((t) && strcmp((t), "float") == 0)
-#define IS_DOUBLE_TYPE(t) ((t) && strcmp((t), "double") == 0)
-#define IS_USIZE_TYPE(t) ((t) && (strcmp((t), "usize") == 0 || strcmp((t), "size_t") == 0))
+#define IS_INT_TYPE(t) ((t) && strcmp((t), "int") == 0)      ///< Checks if type is "int".
+#define IS_BOOL_TYPE(t) ((t) && strcmp((t), "bool") == 0)    ///< Checks if type is "bool".
+#define IS_CHAR_TYPE(t) ((t) && strcmp((t), "char") == 0)    ///< Checks if type is "char".
+#define IS_VOID_TYPE(t) ((t) && strcmp((t), "void") == 0)    ///< Checks if type is "void".
+#define IS_FLOAT_TYPE(t) ((t) && strcmp((t), "float") == 0)  ///< Checks if type is "float".
+#define IS_DOUBLE_TYPE(t) ((t) && strcmp((t), "double") == 0)///< Checks if type is "double".
+#define IS_USIZE_TYPE(t) ((t) && (strcmp((t), "usize") == 0 || strcmp((t), "size_t") == 0)) ///< Checks if type is "usize" or "size_t".
+/**
+ * @brief Checks if type is a string type ("string", "char*", "const char*").
+ */
 #define IS_STRING_TYPE(t)                                                                          \
     ((t) &&                                                                                        \
      (strcmp((t), "string") == 0 || strcmp((t), "char*") == 0 || strcmp((t), "const char*") == 0))
 
 // Composite type checks
+/**
+ * @brief Checks if type is a basic primitive type.
+ */
 #define IS_BASIC_TYPE(t)                                                                           \
     ((t) && (IS_INT_TYPE(t) || IS_BOOL_TYPE(t) || IS_CHAR_TYPE(t) || IS_VOID_TYPE(t) ||            \
              IS_FLOAT_TYPE(t) || IS_DOUBLE_TYPE(t) || IS_USIZE_TYPE(t) ||                          \
              strcmp((t), "ssize_t") == 0 || strcmp((t), "__auto_type") == 0))
 
+/**
+ * @brief Checks if type is numeric (int, float, double, usize).
+ */
 #define IS_NUMERIC_TYPE(t)                                                                         \
     ((t) && (IS_INT_TYPE(t) || IS_FLOAT_TYPE(t) || IS_DOUBLE_TYPE(t) || IS_USIZE_TYPE(t)))
 
 // Pointer type check
-#define IS_PTR_TYPE(t) ((t) && strchr((t), '*') != NULL)
+#define IS_PTR_TYPE(t) ((t) && strchr((t), '*') != NULL) ///< Checks if type string contains '*'.
 
 // Struct prefix check
-#define IS_STRUCT_PREFIX(t) ((t) && strncmp((t), "struct ", 7) == 0)
-#define STRIP_STRUCT_PREFIX(t) (IS_STRUCT_PREFIX(t) ? ((t) + 7) : (t))
+#define IS_STRUCT_PREFIX(t) ((t) && strncmp((t), "struct ", 7) == 0) ///< Checks if type starts with "struct ".
+#define STRIP_STRUCT_PREFIX(t) (IS_STRUCT_PREFIX(t) ? ((t) + 7) : (t)) ///< Returns ptr to name after "struct " prefix.
 
 // Generic type checks
-#define IS_OPTION_TYPE(t) ((t) && strncmp((t), "Option_", 7) == 0)
-#define IS_RESULT_TYPE(t) ((t) && strncmp((t), "Result_", 7) == 0)
-#define IS_VEC_TYPE(t) ((t) && strncmp((t), "Vec_", 4) == 0)
-#define IS_SLICE_TYPE(t) ((t) && strncmp((t), "Slice_", 6) == 0)
+#define IS_OPTION_TYPE(t) ((t) && strncmp((t), "Option_", 7) == 0) ///< Checks if type is Option<T>.
+#define IS_RESULT_TYPE(t) ((t) && strncmp((t), "Result_", 7) == 0) ///< Checks if type is Result<T>.
+#define IS_VEC_TYPE(t) ((t) && strncmp((t), "Vec_", 4) == 0)       ///< Checks if type is Vec<T>.
+#define IS_SLICE_TYPE(t) ((t) && strncmp((t), "Slice_", 6) == 0)   ///< Checks if type is Slice<T>.
 
 #endif // ZEN_CONSTANTS_H
diff --git a/src/lsp/json_rpc.h b/src/lsp/json_rpc.h
index 363f425..98d7ec1 100644
--- a/src/lsp/json_rpc.h
+++ b/src/lsp/json_rpc.h
@@ -2,7 +2,14 @@
 #ifndef JSON_RPC_H
 #define JSON_RPC_H
 
-// Yeah, just this lol.
+/**
+ * @brief Handle a raw JSON-RPC request string.
+ * 
+ * Parses the request, routes it to the appropriate handler (initialize, textDocument/didChange, etc.),
+ * and sends back the response to stdout.
+ * 
+ * @param json_str Null-terminated JSON request string.
+ */
 void handle_request(const char *json_str);
 
 #endif
diff --git a/src/lsp/lsp_index.h b/src/lsp/lsp_index.h
index f4aaf96..1b45c57 100644
--- a/src/lsp/lsp_index.h
+++ b/src/lsp/lsp_index.h
@@ -4,30 +4,39 @@
 
 #include "parser.h"
 
+/**
+ * @brief Type of an indexed AST range.
+ */
 typedef enum
 {
-    RANGE_DEFINITION,
-    RANGE_REFERENCE
+    RANGE_DEFINITION, ///< Defines a symbol.
+    RANGE_REFERENCE   ///< References a symbol.
 } RangeType;
 
+/**
+ * @brief A range in the source code mapping to semantic info.
+ */
 typedef struct LSPRange
 {
-    int start_line;
-    int start_col;
-    int end_line;
-    int end_col; // Approximation.
-    RangeType type;
-    int def_line;
-    int def_col;
-    char *hover_text;
-    ASTNode *node;
+    int start_line;     ///< Start line (1-based).
+    int start_col;      ///< Start column (1-based).
+    int end_line;       ///< End line.
+    int end_col;        ///< End column (approximated).
+    RangeType type;     ///< Type of range (def or ref).
+    int def_line;       ///< Line of definition (if reference).
+    int def_col;        ///< Column of definition (if reference).
+    char *hover_text;   ///< Tooltip text / signature.
+    ASTNode *node;      ///< Associated AST node.
     struct LSPRange *next;
 } LSPRange;
 
+/**
+ * @brief Index of a single file.
+ */
 typedef struct LSPIndex
 {
-    LSPRange *head;
-    LSPRange *tail;
+    LSPRange *head;     ///< First range in the file.
+    LSPRange *tail;     ///< Last range in the file.
 } LSPIndex;
 
 // API.
diff --git a/src/lsp/lsp_project.h b/src/lsp/lsp_project.h
index 9b4fe42..f6d6942 100644
--- a/src/lsp/lsp_project.h
+++ b/src/lsp/lsp_project.h
@@ -4,26 +4,31 @@
 #include "parser.h"
 #include "lsp_index.h"
 
+/**
+ * @brief Represents a tracked file in the LSP project.
+ */
 typedef struct ProjectFile
 {
-    char *path;      // Absolute path
-    char *uri;       // file:// URI
-    char *source;    // Cached source content
-    LSPIndex *index; // File-specific index (local vars, refs)
+    char *path;      ///< Absolute file path.
+    char *uri;       ///< file:// URI.
+    char *source;    ///< Cached source content (in-memory).
+    LSPIndex *index; ///< File-specific symbol index.
     struct ProjectFile *next;
 } ProjectFile;
 
+/**
+ * @brief Global state for the Language Server Project.
+ */
 typedef struct
 {
-    // Global symbol table (Structs, Functions, Globals)
-    // We reuse ParserContext for this, as it already supports registries.
+    /**
+     * @brief Global shared parser context.
+     * Contains global registries (structs, functions) reused across files.
+     */
     ParserContext *ctx;
 
-    // List of tracked files
-    ProjectFile *files;
-
-    // Root directory
-    char *root_path;
+    ProjectFile *files; ///< List of tracked open files.
+    char *root_path;    ///< Project root directory.
 } LSPProject;
 
 // Global project instance
diff --git a/src/plugins/plugin_manager.h b/src/plugins/plugin_manager.h
index 9b35c2d..f5696e6 100644
--- a/src/plugins/plugin_manager.h
+++ b/src/plugins/plugin_manager.h
@@ -4,19 +4,35 @@
 #include "../../plugins/zprep_plugin.h"
 
 // Initialize the plugin system.
+/**
+ * @brief Initialize the plugin system.
+ */
 void zptr_plugin_mgr_init(void);
 
-// Register a plugin directly (for built-ins).
+/**
+ * @brief Register a plugin directly (for built-in plugins).
+ * @param plugin The plugin to register.
+ */
 void zptr_register_plugin(ZPlugin *plugin);
 
-// Load a plugin from a shared object file (.so).
-// Returns ZPlugin pointer on success, NULL on failure.
+/**
+ * @brief Load a plugin from a shared object file (.so).
+ * 
+ * @param path Path to the shared object file.
+ * @return ZPlugin* Pointer to the loaded plugin on success, NULL on failure.
+ */
 ZPlugin *zptr_load_plugin(const char *path);
 
-// Find a registered plugin by name.
+/**
+ * @brief Find a registered plugin by name.
+ * @param name The name of the plugin.
+ * @return ZPlugin* Pointer to the plugin or NULL if not found.
+ */
 ZPlugin *zptr_find_plugin(const char *name);
 
-// Cleanup.
+/**
+ * @brief Cleanup the plugin system and free resources.
+ */
 void zptr_plugin_mgr_cleanup(void);
 
 #endif
diff --git a/src/repl/repl.h b/src/repl/repl.h
index f467b78..2a49288 100644
--- a/src/repl/repl.h
+++ b/src/repl/repl.h
@@ -2,6 +2,11 @@
 #ifndef REPL_H
 #define REPL_H
 
+/**
+ * @brief Starts the Read-Eval-Print Loop (REPL).
+ * 
+ * @param self_path Path to the executable/ZC compiler itself.
+ */
 void run_repl(const char *self_path);
 
 #endif
diff --git a/src/zen/zen_facts.h b/src/zen/zen_facts.h
index ce5b952..329c8fb 100644
--- a/src/zen/zen_facts.h
+++ b/src/zen/zen_facts.h
@@ -4,21 +4,27 @@
 
 #include "../zprep.h"
 
+/**
+ * @brief Triggers for Zen facts (easter egg system).
+ * 
+ * Each trigger corresponds to a specific coding pattern or event
+ * which may elicit a "Zen Fact" message to the user.
+ */
 typedef enum
 {
-    TRIGGER_GOTO,
-    TRIGGER_POINTER_ARITH,
-    TRIGGER_BITWISE,
-    TRIGGER_RECURSION,
-    TRIGGER_TERNARY,
-    TRIGGER_ASM,
-    TRIGGER_WHILE_TRUE,
-    TRIGGER_MACRO,
-    TRIGGER_VOID_PTR,
-    TRIGGER_MAIN,
-    TRIGGER_FORMAT_STRING,
-    TRIGGER_STRUCT_PADDING,
-    TRIGGER_GLOBAL
+    TRIGGER_GOTO,           ///< Usage of `goto`.
+    TRIGGER_POINTER_ARITH,  ///< Pointer arithmetic usage.
+    TRIGGER_BITWISE,        ///< Bitwise operations.
+    TRIGGER_RECURSION,      ///< Recursive calls (currently manual trigger).
+    TRIGGER_TERNARY,        ///< Ternary operator usage.
+    TRIGGER_ASM,            ///< Inline assembly.
+    TRIGGER_WHILE_TRUE,     ///< `while(true)` loops.
+    TRIGGER_MACRO,          ///< Macro definitions.
+    TRIGGER_VOID_PTR,       ///< `void*` usage.
+    TRIGGER_MAIN,           ///< Compilation of `main` function.
+    TRIGGER_FORMAT_STRING,  ///< F-string usage.
+    TRIGGER_STRUCT_PADDING, ///< Implicit padding detection.
+    TRIGGER_GLOBAL          ///< Global variables.
 } ZenTrigger;
 
 void zen_init(void);