Add Doxygen-style file header comments to all .c and .h files

src/backend/codeGeneration/codegen.h

@@ -1,3 +1,12 @@
+/**
+ * @file codegen.h
+ * @brief Public API and context for x86-64 code generation.
+ *
+ * Exposes CodeGenContext, FuncInfo, and all code generation functions
+ * that translate IR instructions into AT&T-syntax x86-64 assembly.
+ * Include this header from any backend module that emits assembly.
+ */
+
 #ifndef CODEGEN_H
 #define CODEGEN_H
 

src/backend/codeGeneration/dataPool.c

@@ -1,3 +1,14 @@
+/**
+ * @file dataPool.c
+ * @brief Constant-data pool management for code generation.
+ *
+ * Responsibilities:
+ *   - addStringLit(): intern and emit .data string constants
+ *   - addDoubleLit(): intern and emit .data double constants
+ *   - addFloatLit(): intern and emit .data float constants
+ *   - findStringLit(): de-duplicate string literals
+ */
+
 #include <stdlib.h>
 #include <string.h>
 #include "codegen.h"

src/backend/codeGeneration/dataPool.h

@@ -1,3 +1,12 @@
+/**
+ * @file dataPool.h
+ * @brief Constant-data pool types and API for code generation.
+ *
+ * Exposes StringEntry, DoubleEntry, FloatEntry structures and
+ * functions for interning string, double, and float literals
+ * into the .data section during assembly generation.
+ */
+
 #ifndef DATA_POOL_H
 #define DATA_POOL_H
 

src/backend/codeGeneration/emiter.c

@@ -1,3 +1,13 @@
+/**
+ * @file emiter.c
+ * @brief Low-level assembly text emission helpers.
+ *
+ * Responsibilities:
+ *   - emitInstruction(): formatted instruction output to text buffer
+ *   - emitASMLabel() / emitLabelNum() / emitDataLabel(): label emission
+ *   - emitComment() / emitBlankLine(): readability helpers
+ */
+
 #include <stdarg.h>
 #include <stdio.h>
 #include "codegen.h"

src/backend/codeGeneration/emiter.h

@@ -1,3 +1,12 @@
+/**
+ * @file emiter.h
+ * @brief Assembly text emission utilities for code generation.
+ *
+ * Exposes helpers for writing labels, instructions, and comments
+ * into the CodeGenContext text buffer. Include from codegen modules
+ * that need to emit raw assembly text.
+ */
+
 #ifndef EMITER_H
 #define EMITER_H
 

src/backend/codeGeneration/stringBuffer.c

@@ -1,3 +1,13 @@
+/**
+ * @file stringBuffer.c
+ * @brief Growable string buffer implementation.
+ *
+ * Responsibilities:
+ *   - sbCreate() / sbFree(): lifecycle management
+ *   - sbAppend() / sbAppendf() / sbAppendChar(): content appending
+ *   - sbEnsureCapacity(): automatic buffer growth
+ */
+
 #include <stdlib.h>
 #include <string.h>
 #include <stdio.h>

src/backend/codeGeneration/stringBuffer.h

@@ -1,3 +1,11 @@
+/**
+ * @file stringBuffer.h
+ * @brief Growable string buffer API for assembly text accumulation.
+ *
+ * Exposes the StringBuffer struct and append/format functions used
+ * by the code generator to build the final assembly output.
+ */
+
 #ifndef STRING_BUFFER_H
 #define STRING_BUFFER_H
 

src/backend/codeGeneration/variableHandling.c

@@ -1,3 +1,16 @@
+/**
+ * @file variableHandling.c
+ * @brief Stack variable and temporary location management for codegen.
+ *
+ * Responsibilities:
+ *   - addLocalVar() / addGlobalVar(): allocate stack slots for variables
+ *   - findVar() / getVarOffset(): variable location lookup
+ *   - addTemp() / findTemp() / getTempOffset(): temporary management
+ *   - markVarAsAddresable(): promote a variable to an addressable slot
+ *   - getIntReg() / getSSEReg(): register selection by type and size
+ *   - getTypeSize() / getIntSuffix() / getSSESuffix(): type utilities
+ */
+
 #include <stdlib.h>
 #include <string.h>
 #include "codegen.h"

src/backend/codeGeneration/variableHandling.h

@@ -1,3 +1,12 @@
+/**
+ * @file variableHandling.h
+ * @brief Stack layout types and API for variable/temporary tracking.
+ *
+ * Exposes VarLoc, TempLoc structures and functions for managing
+ * stack slot allocation, register selection, and type-size queries
+ * during code generation.
+ */
+
 #ifndef VARIABLE_HANDLING_H
 #define VARIABLE_HANDLING_H
 

src/errorHandling/errors.c

@@ -1,3 +1,14 @@
+/**
+ * @file errors.c
+ * @brief Error database: definitions and messages for all compiler diagnostics.
+ *
+ * Responsibilities:
+ *   - errorDatabase[]: static table mapping ErrorCode → severity, message, hint
+ *   - Provides the single source of truth for all error/warning strings
+ *
+ * This file is data-only; no logic beyond the table lives here.
+ */
+
 #include "errorHandling.h"
 
 const ErrorInfo errorDatabase[] = {

src/frontend/lexer/lexer.c

@@ -1,3 +1,14 @@
+/**
+ * @file lexer.c
+ * @brief Tokenizer / lexical analysis implementation.
+ *
+ * Responsibilities:
+ *   - lex(): scan source text and produce a TokenList
+ *   - Token creation, keyword recognition, and literal scanning
+ *   - Whitespace / comment skipping and line tracking
+ *   - freeTokens(): deallocate a token list
+ */
+
 #include "lexer.h"
 #include <ctype.h>
 #include <stdlib.h>

src/frontend/lexer/lexer.h

@@ -1,3 +1,12 @@
+/**
+ * @file lexer.h
+ * @brief Public API for the Orn lexer (tokenizer).
+ *
+ * Exposes token types, the Token / TokenList structures, and the
+ * lex() entry point. Include this header from the parser or any
+ * module that needs to consume tokens.
+ */
+
 #ifndef LEXER_H
 #define LEXER_H
 

src/main.c

@@ -1,3 +1,14 @@
+/**
+ * @file main.c
+ * @brief Compiler entry point and command-line interface driver.
+ *
+ * Responsibilities:
+ *   - Parse command-line arguments (input file, output, flags)
+ *   - Orchestrate the full compilation pipeline via buildProject()
+ *   - Process CLI flags: -o, -O, -v, --ast, --ir
+ *   - Print usage information
+ */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>

src/middleend/IR/ir.c

@@ -1,3 +1,18 @@
+/**
+ * @file ir.c
+ * @brief Intermediate Representation (IR) generation from the AST.
+ *
+ * Responsibilities:
+ *   - createIrContext() / freeIrContext()
+ *   - Operand constructors (createTemp, createVar, createConst, …)
+ *   - IR instruction emission (emitBinary, emitCopy, emitLabel, …)
+ *   - symbolTypeToIrType() / nodeTypeToIrType() / astOpToIrOp(): mappings
+ *   - generateExpressionIr(): expression → IR lowering
+ *   - generateStatementIr(): statement → IR lowering
+ *   - generateIr(): top-level AST → IR entry point
+ *   - printIR(): debug dump of the instruction list
+ */
+
 #include "ir.h"
 #include <stdlib.h>
 #include <stdio.h>

src/middleend/IR/ir.h

@@ -1,3 +1,12 @@
+/**
+ * @file ir.h
+ * @brief Intermediate Representation types, opcodes, and generation API.
+ *
+ * Exposes IrOpCode, IrDataType, IrOperand, IrInstruction, IrContext,
+ * and the functions for creating, emitting, and generating IR from
+ * a type-checked AST. Include from middleend and backend modules.
+ */
+
 #include <stddef.h>
 #include <stdint.h>
 #include "semantic.h"

src/middleend/IR/irHelpers.c

@@ -1,3 +1,14 @@
+/**
+ * @file irHelpers.c
+ * @brief Parsing and comparison utilities for IR generation.
+ *
+ * Responsibilities:
+ *   - parseInt(): parse an integer from a source buffer
+ *   - parseFloat(): parse a floating-point value from a source buffer
+ *   - matchLit(): compare a buffer to a literal string
+ *   - bufferEqual(): length-prefixed buffer comparison
+ */
+
 #include <string.h>
 #include <ctype.h>
 #include <parser.h>

src/middleend/IR/irHelpers.h

@@ -1,3 +1,11 @@
+/**
+ * @file irHelpers.h
+ * @brief Utility functions for parsing literals and buffer comparison.
+ *
+ * Exposes parseInt(), parseFloat(), matchLit(), and bufferEqual()
+ * used during IR generation to interpret AST node content.
+ */
+
 #ifndef IRHELPERS_H
 #define IRHELPERS_H
 

src/middleend/IR/optimization.c

@@ -1,3 +1,14 @@
+/**
+ * @file optimization.c
+ * @brief IR optimization passes.
+ *
+ * Responsibilities:
+ *   - constantFolding(): evaluate constant expressions at compile time
+ *   - copyProp(): propagate copies to eliminate redundant assignments
+ *   - deadCodeElimination(): remove unused instructions
+ *   - optimizeIR(): run iterative optimization pipeline at a given level
+ */
+
 #include "ir.h"
 #include <stdlib.h>
 #include "irHelpers.h"

src/middleend/IR/optimization.h

@@ -1,3 +1,12 @@
+/**
+ * @file optimization.h
+ * @brief IR optimization pass declarations.
+ *
+ * Exposes constantFolding(), copyProp(), deadCodeElimination(),
+ * and the top-level optimizeIR() entry point. Include from modules
+ * that need to run optimizations on the IR before code generation.
+ */
+
 void constantFolding(IrContext *ctx);
 void copyProp(IrContext *ctx);
 void deadCodeElimination(IrContext *ctx);

src/modules/build.c

@@ -1,3 +1,15 @@
+/**
+ * @file build.c
+ * @brief Multi-module build system and compilation orchestrator.
+ *
+ * Responsibilities:
+ *   - findModules(): recursive module discovery from imports
+ *   - topoSortModules(): topological sort for compilation order
+ *   - buildProject(): end-to-end build pipeline (lex → parse → typecheck → IR → codegen → link)
+ *   - extractImports(): extract import declarations from an AST
+ *   - resolveModulePath(): resolve a module name to a filesystem path
+ */
+
 #include "build.h"
 #include <stdio.h>
 #include <stdlib.h>

src/modules/build.h

@@ -1,3 +1,12 @@
+/**
+ * @file build.h
+ * @brief Multi-module build system API.
+ *
+ * Exposes Module, BuildContext structures and functions for
+ * discovering, sorting, compiling, and linking Orn modules.
+ * Include from main.c or any driver that orchestrates builds.
+ */
+
 #ifndef BUILD_H
 #define BUILD_H
 

src/modules/interface.c

@@ -1,3 +1,14 @@
+/**
+ * @file interface.c
+ * @brief Module interface extraction and symbol import logic.
+ *
+ * Responsibilities:
+ *   - extractExportsWithContext(): walk the AST to collect exported functions/structs
+ *   - addImportsToSymbolTable(): register imported symbols for type-checking
+ *   - dataTypeToString() / stringToDataType(): type ↔ string conversion
+ *   - freeModuleInterface(): memory cleanup
+ */
+
 #include "interface.h"
 
 #include <stdio.h>

src/modules/interface.h

@@ -1,3 +1,12 @@
+/**
+ * @file interface.h
+ * @brief Module interface types and API for cross-module imports/exports.
+ *
+ * Exposes ModuleInterface, ExportedFunction, ExportedStruct, and
+ * ExportedField structures along with functions for extracting exports,
+ * injecting imports into symbol tables, and type string conversions.
+ */
+
 #ifndef INTERFACE_H
 #define INTERFACE_H