Better documentation

4 files changed, 299 insertions, 201 deletions

diff --git a/Doxyfile b/Doxyfile
index 88618b1..90777b0 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -2682,7 +2682,7 @@ INCLUDED_BY_GRAPH      = YES
 # The default value is: NO.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-CALL_GRAPH             = NO
+CALL_GRAPH             = YES
 
 # If the CALLER_GRAPH tag is set to YES then doxygen will generate a caller
 # dependency graph for every global function or class method.
@@ -2694,7 +2694,7 @@ CALL_GRAPH             = NO
 # The default value is: NO.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-CALLER_GRAPH           = NO
+CALLER_GRAPH           = YES
 
 # If the GRAPHICAL_HIERARCHY tag is set to YES then doxygen will graphical
 # hierarchy of all classes instead of a textual one.
diff --git a/src/codegen/codegen.h b/src/codegen/codegen.h
index 942de41..ec77817 100644
--- a/src/codegen/codegen.h
+++ b/src/codegen/codegen.h
@@ -8,10 +8,34 @@
 #include <stdio.h>
 
 // Main codegen entry points.
+
+/**
+ * @brief Generates code for a given AST node.
+ * 
+ * @param ctx Parser context.
+ * @param node The AST node to generate code for.
+ * @param out Output file stream.
+ */
 void codegen_node(ParserContext *ctx, ASTNode *node, FILE *out);
+
+/**
+ * @brief Generates code for a single AST node (non-recursive for siblings).
+ */
 void codegen_node_single(ParserContext *ctx, ASTNode *node, FILE *out);
+
+/**
+ * @brief Walker for list of nodes (calls codegen_node recursively).
+ */
 void codegen_walker(ParserContext *ctx, ASTNode *node, FILE *out);
+
+/**
+ * @brief Generates code for an expression node.
+ */
 void codegen_expression(ParserContext *ctx, ASTNode *node, FILE *out);
+
+/**
+ * @brief Internal handler for match statements.
+ */
 void codegen_match_internal(ParserContext *ctx, ASTNode *node, FILE *out, int use_result);
 
 // Utility functions (codegen_utils.c).
@@ -26,7 +50,7 @@ void emit_auto_type(ParserContext *ctx, ASTNode *init_expr, Token t, FILE *out);
 char *codegen_type_to_string(Type *t);
 void emit_func_signature(FILE *out, ASTNode *func, const char *name_override);
 char *strip_template_suffix(const char *name);
-char *strip_template_suffix(const char *name);
+// duplicate decl removed: char *strip_template_suffix(const char *name);
 int emit_move_invalidation(ParserContext *ctx, ASTNode *node, FILE *out);
 void codegen_expression_with_move(ParserContext *ctx, ASTNode *node, FILE *out);
 
@@ -46,19 +70,19 @@ int emit_tests_and_runner(ParserContext *ctx, ASTNode *node, FILE *out);
 void print_type_defs(ParserContext *ctx, FILE *out, ASTNode *nodes);
 
 // Global state (shared across modules).
-extern ASTNode *global_user_structs;
-extern char *g_current_impl_type;
-extern int tmp_counter;
-extern int defer_count;
-extern ASTNode *defer_stack[];
-extern ASTNode *g_current_lambda;
-extern char *g_current_func_ret_type;
+extern ASTNode *global_user_structs;    ///< List of user defined structs.
+extern char *g_current_impl_type;       ///< Type currently being implemented (in impl block).
+extern int tmp_counter;                 ///< Counter for temporary variables.
+extern int defer_count;                 ///< Counter for defer statements in current scope.
+extern ASTNode *defer_stack[];          ///< Stack of deferred nodes.
+extern ASTNode *g_current_lambda;       ///< Current lambda being generated.
+extern char *g_current_func_ret_type;   ///< Return type of current function.
 
 // Defer boundary tracking for proper defer execution on break/continue/return
 #define MAX_DEFER 1024
 #define MAX_LOOP_DEPTH 64
-extern int loop_defer_boundary[]; // defer_count at each loop entry
-extern int loop_depth;            // current loop nesting depth
-extern int func_defer_boundary;   // defer_count at function entry
+extern int loop_defer_boundary[];       ///< Defer stack index at start of each loop.
+extern int loop_depth;                  ///< Current loop nesting depth.
+extern int func_defer_boundary;         ///< Defer stack index at function entry.
 
 #endif
diff --git a/src/parser/parser.h b/src/parser/parser.h
index eb8682d..807f37d 100644
--- a/src/parser/parser.h
+++ b/src/parser/parser.h
@@ -32,95 +32,131 @@ ASTNode *parse_program(ParserContext *ctx, Lexer *l);
 extern ParserContext *g_parser_ctx;
 
 // Symbol table
+/**
+ * @brief Represents a symbol in the symbol table.
+ * 
+ * Used for variables, functions, and other named entities.
+ */
 typedef struct ZenSymbol
 {
-    char *name;
-    char *type_name;
-    Type *type_info;
-    int is_used;
-    int is_autofree;
-    Token decl_token;
-    int is_const_value;
-    int is_def;
-    int const_int_val;
-    int is_moved;
-    struct ZenSymbol *next;
+    char *name;             ///< Symbol name.
+    char *type_name;        ///< String representation of the type.
+    Type *type_info;        ///< Formal type definition.
+    int is_used;            ///< 1 if the symbol has been referenced.
+    int is_autofree;        ///< 1 if it requires automatic memory management (RAII).
+    Token decl_token;       ///< Token where the symbol was declared.
+    int is_const_value;     ///< 1 if it is a compile-time constant.
+    int is_def;             ///< 1 if it is a definition (vs declaration).
+    int const_int_val;      ///< Integer value if it is a constant.
+    int is_moved;           ///< 1 if the value has been moved (ownership transfer).
+    struct ZenSymbol *next; ///< Next symbol in the bucket/list (chaining).
 } ZenSymbol;
 
+/**
+ * @brief Represents a lexical scope (block).
+ * 
+ * Scopes form a hierarchy (parent pointer) and contain a list of symbols defined in that scope.
+ */
 typedef struct Scope
 {
-    ZenSymbol *symbols;
-    struct Scope *parent;
+    ZenSymbol *symbols;     ///< Linked list of symbols in this scope.
+    struct Scope *parent;   ///< Pointer to the parent scope (NULL for global).
 } Scope;
 
-// Function registry
+/**
+ * @brief Registry entry for a function signature.
+ * 
+ * Stores metadata about declared functions for type checking and call validation.
+ */
 typedef struct FuncSig
 {
-    char *name;
-    Token decl_token;
-    int total_args;
-    char **defaults;
-    Type **arg_types;
-    Type *ret_type;
-    int is_varargs;
-    int is_async;
-    int must_use;
-    struct FuncSig *next;
+    char *name;             ///< Function name.
+    Token decl_token;       ///< declaration token.
+    int total_args;         ///< Total argument count.
+    char **defaults;        ///< Default values for arguments (or NULL).
+    Type **arg_types;       ///< Argument types.
+    Type *ret_type;         ///< Return type.
+    int is_varargs;         ///< 1 if variadic.
+    int is_async;           ///< 1 if async.
+    int must_use;           ///< 1 if return value must be used.
+    struct FuncSig *next;   ///< Next function in registry.
 } FuncSig;
 
-// Lambda tracking
+/**
+ * @brief Tracks a lambda (anonymous function) within the parser.
+ */
 typedef struct LambdaRef
 {
-    ASTNode *node;
+    ASTNode *node;          ///< The AST node for the lambda.
     struct LambdaRef *next;
 } LambdaRef;
 
+/**
+ * @brief Template for a generic struct.
+ */
 typedef struct GenericTemplate
 {
-    char *name;
-    ASTNode *struct_node;
+    char *name;             ///< Template name.
+    ASTNode *struct_node;   ///< The struct AST node (containing generic params).
     struct GenericTemplate *next;
 } GenericTemplate;
 
+/**
+ * @brief Template for a generic function.
+ */
 typedef struct GenericFuncTemplate
 {
-    char *name;
-    char *generic_param;
-    ASTNode *func_node;
+    char *name;             ///< Template name.
+    char *generic_param;    ///< Generic parameters string (legacy).
+    ASTNode *func_node;     ///< The function AST node.
     struct GenericFuncTemplate *next;
 } GenericFuncTemplate;
 
+/**
+ * @brief Template for a generic implementation block.
+ */
 typedef struct GenericImplTemplate
 {
-    char *struct_name;
-    char *generic_param;
-    ASTNode *impl_node;
+    char *struct_name;      ///< Target struct name.
+    char *generic_param;    ///< Generic parameters.
+    ASTNode *impl_node;     ///< The impl block AST node.
     struct GenericImplTemplate *next;
 } GenericImplTemplate;
 
+/**
+ * @brief Represents an imported source file (to prevent cycles/duplication).
+ */
 typedef struct ImportedFile
 {
-    char *path;
+    char *path;             ///< Absolute file path.
     struct ImportedFile *next;
 } ImportedFile;
 
-// Instantiation tracking
+/**
+ * @brief Tracks a concrete instantiation of a generic template.
+ */
 typedef struct Instantiation
 {
-    char *name;
-    char *template_name;
-    char *concrete_arg;
-    char *unmangled_arg; // For code substitution (e.g. "struct T*")
-    ASTNode *struct_node;
+    char *name;             ///< Mangled name of the instantiation (e.g. "Vec_int").
+    char *template_name;    ///< Original template name (e.g. "Vec").
+    char *concrete_arg;     ///< Concrete type argument string.
+    char *unmangled_arg;    ///< Unmangled argument for substitution code.
+    ASTNode *struct_node;   ///< The AST node of the instantiated struct.
     struct Instantiation *next;
 } Instantiation;
 
+/**
+ * @brief Reference to a parsed struct (list node).
+ */
 typedef struct StructRef
 {
     ASTNode *node;
     struct StructRef *next;
 } StructRef;
 
+/**
+ * @brief Definition of a struct (lookup cache).
+ */
 typedef struct StructDef
 {
     char *name;
@@ -128,152 +164,179 @@ typedef struct StructDef
     struct StructDef *next;
 } StructDef;
 
-// Type tracking
+/**
+ * @brief Track used slice types for generation.
+ */
 typedef struct SliceType
 {
     char *name;
     struct SliceType *next;
 } SliceType;
 
+/**
+ * @brief Track used tuple signatures for generation.
+ */
 typedef struct TupleType
 {
     char *sig;
     struct TupleType *next;
 } TupleType;
 
-// Enum tracking
+/**
+ * @brief Registry of enum variants.
+ */
 typedef struct EnumVariantReg
 {
-    char *enum_name;
-    char *variant_name;
-    int tag_id;
+    char *enum_name;        ///< Name of the enum.
+    char *variant_name;     ///< Name of the variant.
+    int tag_id;             ///< Integration tag value.
     struct EnumVariantReg *next;
 } EnumVariantReg;
 
-// Deprecated function tracking
+/**
+ * @brief Functions marked as deprecated.
+ */
 typedef struct DeprecatedFunc
 {
     char *name;
-    char *reason; // Optional reason message
+    char *reason;           ///< Optional reason for deprecation.
     struct DeprecatedFunc *next;
 } DeprecatedFunc;
 
-// Module system
+/**
+ * @brief Represents a module (namespace/file).
+ */
 typedef struct Module
 {
-    char *alias;
-    char *path;
-    char *base_name;
-    int is_c_header;
+    char *alias;            ///< Import alias (or default name).
+    char *path;             ///< File path.
+    char *base_name;        ///< Base name of the module.
+    int is_c_header;        ///< 1 if this is a C header import.
     struct Module *next;
 } Module;
 
+/**
+ * @brief Symbol imported via selective import (import { X }).
+ */
 typedef struct SelectiveImport
 {
-    char *symbol;
-    char *alias;
-    char *source_module;
+    char *symbol;           ///< Symbol name.
+    char *alias;            ///< Local alias.
+    char *source_module;    ///< Origin module.
     struct SelectiveImport *next;
 } SelectiveImport;
 
-// Impl cache
+/**
+ * @brief Registry for trait implementations.
+ */
 typedef struct ImplReg
 {
-    char *trait;
-    char *strct;
+    char *trait;            ///< Trait name.
+    char *strct;            ///< Implementing struct name.
     struct ImplReg *next;
 } ImplReg;
 
-// Plugin tracking
+/**
+ * @brief Loaded compiler plugin.
+ */
 typedef struct ImportedPlugin
 {
-    char *name;  // Original plugin name (for example, "brainfuck")
-    char *alias; // Optional alias (for example, "bf"), NULL if no alias
+    char *name;             ///< Plugin name (e.g., "brainfuck").
+    char *alias;            ///< Optional usage alias.
     struct ImportedPlugin *next;
 } ImportedPlugin;
 
+/**
+ * @brief Type alias definition.
+ */
 typedef struct TypeAlias
 {
-    char *alias;
-    char *original_type;
+    char *alias;            ///< New type name.
+    char *original_type;    ///< Original type.
     struct TypeAlias *next;
 } TypeAlias;
 
+/**
+ * @brief Global compilation state and symbol table.
+ * 
+ * ParserContext maintains the state of the compiler during parsing and analysis.
+ * It holds symbol tables, type definitions, function registries, and configuration.
+ */
 struct ParserContext
 {
-    Scope *current_scope;
-    FuncSig *func_registry;
+    Scope *current_scope;       ///< Current lexical scope for variable lookup.
+    FuncSig *func_registry;     ///< Registry of declared function signatures.
 
     // Lambdas
-    LambdaRef *global_lambdas;
-    int lambda_counter;
+    LambdaRef *global_lambdas;  ///< List of all lambdas generated during parsing.
+    int lambda_counter;         ///< Counter for generating unique lambda IDs.
 
 // Generics
 #define MAX_KNOWN_GENERICS 1024
-    char *known_generics[MAX_KNOWN_GENERICS];
-    int known_generics_count;
-    GenericTemplate *templates;
-    GenericFuncTemplate *func_templates;
-    GenericImplTemplate *impl_templates;
+    char *known_generics[MAX_KNOWN_GENERICS]; ///< Stack of currently active generic type parameters.
+    int known_generics_count;                 ///< Count of active generic parameters.
+    GenericTemplate *templates;               ///< Struct generic templates.
+    GenericFuncTemplate *func_templates;      ///< Function generic templates.
+    GenericImplTemplate *impl_templates;      ///< Implementation block templates.
 
     // Instantiations
-    Instantiation *instantiations;
-    ASTNode *instantiated_structs;
-    ASTNode *instantiated_funcs;
+    Instantiation *instantiations;      ///< Cache of instantiated generic types.
+    ASTNode *instantiated_structs;      ///< List of AST nodes for instantiated structs.
+    ASTNode *instantiated_funcs;        ///< List of AST nodes for instantiated functions.
 
     // Structs/Enums
-    StructRef *parsed_structs_list;
-    StructRef *parsed_enums_list;
-    StructRef *parsed_funcs_list;
-    StructRef *parsed_impls_list;
-    StructRef *parsed_globals_list;
-    StructDef *struct_defs;
-    EnumVariantReg *enum_variants;
-    ImplReg *registered_impls;
+    StructRef *parsed_structs_list;     ///< List of all parsed struct nodes.
+    StructRef *parsed_enums_list;       ///< List of all parsed enum nodes.
+    StructRef *parsed_funcs_list;       ///< List of all parsed function nodes.
+    StructRef *parsed_impls_list;       ///< List of all parsed impl blocks.
+    StructRef *parsed_globals_list;     ///< List of all parsed global variables.
+    StructDef *struct_defs;             ///< Registry of struct definitions (map name -> node).
+    EnumVariantReg *enum_variants;      ///< Registry of enum variants for global lookup.
+    ImplReg *registered_impls;          ///< Cache of type/trait implementations.
 
     // Types
-    SliceType *used_slices;
-    TupleType *used_tuples;
-    TypeAlias *type_aliases;
+    SliceType *used_slices;             ///< Cache of generated slice types.
+    TupleType *used_tuples;             ///< Cache of generated tuple types.
+    TypeAlias *type_aliases;            ///< Defined type aliases.
 
     // Modules/Imports
-    Module *modules;
-    SelectiveImport *selective_imports;
-    char *current_module_prefix;
-    ImportedFile *imported_files;
-    ImportedPlugin *imported_plugins; // Plugin imports
+    Module *modules;                    ///< List of registered modules.
+    SelectiveImport *selective_imports; ///< Symbols imported via `import { ... }`.
+    char *current_module_prefix;        ///< Prefix for current module (namespacing).
+    ImportedFile *imported_files;       ///< List of files already included/imported.
+    ImportedPlugin *imported_plugins;   ///< List of active plugins.
 
     // Config/State
-    char *current_impl_struct;
-    ASTNode *current_impl_methods; // Head of method list for current impl block
+    char *current_impl_struct;          ///< Name of struct currently being implemented (in impl block).
+    ASTNode *current_impl_methods;      ///< Head of method list for current impl block.
 
     // Internal tracking
-    DeprecatedFunc *deprecated_funcs;
+    DeprecatedFunc *deprecated_funcs;   ///< Registry of deprecated functions.
 
     // LSP / Fault Tolerance
-    int is_fault_tolerant;
-    void *error_callback_data;
-    void (*on_error)(void *data, Token t, const char *msg);
+    int is_fault_tolerant;              ///< 1 if parser should recover from errors (LSP mode).
+    void *error_callback_data;          ///< User data for error callback.
+    void (*on_error)(void *data, Token t, const char *msg); ///< Callback for reporting errors.
 
     // LSP: Flat symbol list (persists after parsing for LSP queries)
-    ZenSymbol *all_symbols;
+    ZenSymbol *all_symbols;             ///< comprehensive list of all symbols seen.
 
     // External C interop: suppress undefined warnings for external symbols
-    int has_external_includes; // Set when include <...> is used
-    char **extern_symbols;     // Explicitly declared extern symbols
-    int extern_symbol_count;
+    int has_external_includes;          ///< Set when `#include <...>` is used.
+    char **extern_symbols;              ///< Explicitly declared extern symbols.
+    int extern_symbol_count;            ///< Count of external symbols.
 
     // Codegen state:
-    FILE *hoist_out;    // For plugins to hoist code to file scope
-    int skip_preamble;  // If 1, codegen_node(NODE_ROOT) won't emit preamble
-    int is_repl;        // REPL mode flag
-    int has_async;      // Track if async features are used
-    int in_defer_block; // Track if currently parsing inside a defer block
+    FILE *hoist_out;    ///< File stream for hoisting code (e.g. from plugins).
+    int skip_preamble;  ///< If 1, codegen won't emit standard preamble (includes etc).
+    int is_repl;        ///< 1 if running in REPL mode.
+    int has_async;      ///< 1 if async/await features are used in the program.
+    int in_defer_block; ///< 1 if currently parsing inside a defer block.
 
     // Type Validation
-    struct TypeUsage *pending_type_validations;
-    int is_speculative;  // Flag to suppress side effects during speculative parsing
-    int silent_warnings; // Suppress warnings (for example, during codegen interpolation)
+    struct TypeUsage *pending_type_validations; ///< List of types to validate after parsing.
+    int is_speculative;  ///< Flag to suppress side effects during speculative parsing.
+    int silent_warnings; ///< Suppress warnings (e.g., during codegen interpolation).
 };
 
 typedef struct TypeUsage
diff --git a/src/zprep.h b/src/zprep.h
index 8f4684f..0fcd76f 100644
--- a/src/zprep.h
+++ b/src/zprep.h
@@ -51,78 +51,87 @@
 // ** GLOBAL STATE **
 extern char *g_current_filename;
 
+/**
+ * @brief Token types for the Lexer.
+ */
 typedef enum
 {
-    TOK_EOF = 0,
-    TOK_IDENT,
-    TOK_INT,
-    TOK_FLOAT,
-    TOK_STRING,
-    TOK_FSTRING,
-    TOK_CHAR,
-    TOK_LPAREN,
-    TOK_RPAREN,
-    TOK_LBRACE,
-    TOK_RBRACE,
-    TOK_LBRACKET,
-    TOK_RBRACKET,
-    TOK_LANGLE,
-    TOK_RANGLE,
-    TOK_COMMA,
-    TOK_COLON,
-    TOK_SEMICOLON,
-    TOK_OP,
-    TOK_AT,
-    TOK_DOTDOT,
-    TOK_DOTDOT_EQ,
-    TOK_DOTDOT_LT,
-    TOK_ARROW,
-    TOK_PIPE,
-    TOK_TEST,
-    TOK_ASSERT,
-    TOK_SIZEOF,
-    TOK_DEF,
-    TOK_DEFER,
-    TOK_AUTOFREE,
-    TOK_QUESTION,
-    TOK_USE,
-    TOK_QQ,
-    TOK_QQ_EQ,
-    TOK_Q_DOT,
-    TOK_DCOLON,
-    TOK_TRAIT,
-    TOK_IMPL,
-    TOK_AND,
-    TOK_OR,
-    TOK_FOR,
-    TOK_COMPTIME,
-    TOK_ELLIPSIS,
-    TOK_UNION,
-    TOK_ASM,
-    TOK_VOLATILE,
-    TOK_ASYNC,
-    TOK_AWAIT,
-    TOK_PREPROC,
-    TOK_ALIAS,
-    TOK_COMMENT,
-    TOK_UNKNOWN
+    TOK_EOF = 0,    ///< End of File.
+    TOK_IDENT,      ///< Identifier (variable, function name).
+    TOK_INT,        ///< Integer literal.
+    TOK_FLOAT,      ///< Float literal.
+    TOK_STRING,     ///< String literal.
+    TOK_FSTRING,    ///< Formatted string literal (f"val is {x}").
+    TOK_CHAR,       ///< Character literal.
+    TOK_LPAREN,     ///< (
+    TOK_RPAREN,     ///< )
+    TOK_LBRACE,     ///< {
+    TOK_RBRACE,     ///< }
+    TOK_LBRACKET,   ///< [
+    TOK_RBRACKET,   ///< ]
+    TOK_LANGLE,     ///< <
+    TOK_RANGLE,     ///< >
+    TOK_COMMA,      ///< ,
+    TOK_COLON,      ///< :
+    TOK_SEMICOLON,  ///< ;
+    TOK_OP,         ///< General operator (e.g. +, *, /).
+    TOK_AT,         ///< @
+    TOK_DOTDOT,     ///< ..
+    TOK_DOTDOT_EQ,  ///< ..= (inclusive range).
+    TOK_DOTDOT_LT,  ///< ..< (exclusive range, explicit).
+    TOK_ARROW,      ///< -> or =>
+    TOK_PIPE,       ///< |> (pipe operator).
+    TOK_TEST,       ///< 'test' keyword.
+    TOK_ASSERT,     ///< 'assert' keyword.
+    TOK_SIZEOF,     ///< 'sizeof' keyword.
+    TOK_DEF,        ///< 'def' keyword.
+    TOK_DEFER,      ///< 'defer' keyword.
+    TOK_AUTOFREE,   ///< 'autofree' keyword.
+    TOK_QUESTION,   ///< ?
+    TOK_USE,        ///< 'use' keyword.
+    TOK_QQ,         ///< ?? (null coalescing).
+    TOK_QQ_EQ,      ///< ??=
+    TOK_Q_DOT,      ///< ?. (optional chaining).
+    TOK_DCOLON,     ///< ::
+    TOK_TRAIT,      ///< 'trait' keyword.
+    TOK_IMPL,       ///< 'impl' keyword.
+    TOK_AND,        ///< 'and' keyword.
+    TOK_OR,         ///< 'or' keyword.
+    TOK_FOR,        ///< 'for' keyword.
+    TOK_COMPTIME,   ///< 'comptime' keyword.
+    TOK_ELLIPSIS,   ///< ...
+    TOK_UNION,      ///< 'union' keyword.
+    TOK_ASM,        ///< 'asm' keyword.
+    TOK_VOLATILE,   ///< 'volatile' keyword.
+    TOK_ASYNC,      ///< 'async' keyword.
+    TOK_AWAIT,      ///< 'await' keyword.
+    TOK_PREPROC,    ///< Preprocessor directive (#...).
+    TOK_ALIAS,      ///< 'alias' keyword.
+    TOK_COMMENT,    ///< Comment (usually skipped).
+    TOK_UNKNOWN     ///< Unknown token.
 } TokenType;
 
+/**
+ * @brief Represents a source token.
+ */
 typedef struct
 {
-    TokenType type;
-    const char *start;
-    int len;
-    int line;
-    int col;
+    TokenType type;     ///< Type of the token.
+    const char *start;  ///< Pointer to start of token in source buffer.
+    int len;            ///< Length of the token text.
+    int line;           ///< Line number (1-based).
+    int col;            ///< Column number (1-based).
 } Token;
 
+/**
+ * @brief Lexer state.
+ */
 typedef struct
 {
-    const char *src;
-    int pos;
-    int line;
-    int col;
+    const char *src;    ///< Source code buffer.
+    int pos;            ///< Current position index.
+    int line;           ///< Current line number.
+    int col;            ///< Current column number.
 } Lexer;
 
 void lexer_init(Lexer *l, const char *src);
@@ -189,30 +198,32 @@ void warn_array_bounds(Token t, int index, int size);
 void warn_format_string(Token t, int arg_num, const char *expected, const char *got);
 void warn_null_pointer(Token t, const char *expr);
 
-// ** Compiler Config **
+/**
+ * @brief Compiler configuration and flags.
+ */
 typedef struct
 {
-    char *input_file;
-    char *output_file;
+    char *input_file;       ///< Input source file path.
+    char *output_file;      ///< Output binary file path.
 
     // Modes.
-    int mode_run;        // 1 if 'run' command.
-    int mode_check;      // 1 if 'check' command or --check.
-    int emit_c;          // 1 if --emit-c (keep C file).
-    int verbose;         // 1 if --verbose.
-    int quiet;           // 1 if --quiet.
-    int no_zen;          // 1 if --no-zen (disable zen facts).
-    int repl_mode;       // 1 if --repl (internal flag for REPL usage).
-    int is_freestanding; // 1 if --freestanding.
-    int mode_transpile;  // 1 if 'transpile' command.
-    int use_cpp;         // 1 if --cpp (emit C++ compatible code).
-    int use_cuda;        // 1 if --cuda (emit CUDA-compatible code).
+    int mode_run;           ///< 1 if 'run' command (compile & execute).
+    int mode_check;         ///< 1 if 'check' command (syntax/type check only).
+    int emit_c;             ///< 1 if --emit-c (keep generated C file).
+    int verbose;            ///< 1 if --verbose.
+    int quiet;              ///< 1 if --quiet.
+    int no_zen;             ///< 1 if --no-zen (disable zen facts/easter eggs).
+    int repl_mode;          ///< 1 if --repl (internal flag for REPL usage).
+    int is_freestanding;    ///< 1 if --freestanding (no stdlib).
+    int mode_transpile;     ///< 1 if 'transpile' command (to C).
+    int use_cpp;            ///< 1 if --cpp (emit C++ compatible code).
+    int use_cuda;           ///< 1 if --cuda (emit CUDA-compatible code).
 
     // GCC Flags accumulator.
-    char gcc_flags[4096];
+    char gcc_flags[4096];   ///< Flags passed to the backend compiler.
 
     // C Compiler selection (default: gcc)
-    char cc[64];
+    char cc[64];            ///< Backend compiler command (e.g. "gcc", "clang").
 } CompilerConfig;
 
 extern CompilerConfig g_config;