continue to polish modules of Ora pipeline

Author: ngmachado

src/ast/ast_serializer.zig

@@ -1,3 +1,26 @@
+// ============================================================================
+// AST Serializer
+// ============================================================================
+//
+// Serializes AST nodes to JSON format with comprehensive customization options.
+//
+// FEATURES:
+//   • Multiple output formats (JSON, compact, pretty-printed)
+//   • Optional span/type/lexeme inclusion
+//   • Depth limiting for large trees
+//   • Streaming to writer for memory efficiency
+//
+// SECTIONS:
+//   • Options & initialization
+//   • Core serialization infrastructure
+//   • Top-level node serialization
+//   • Statement serialization
+//   • Expression serialization
+//   • Helper serializers
+//   • Pattern serializers
+//
+// ============================================================================
+
 const std = @import("std");
 const ast = @import("../ast.zig");
 const AstNode = ast.AstNode;
@@ -173,6 +196,15 @@ pub const AstSerializer = struct {
         }
     }
 
+    // ========================================================================
+    // TOP-LEVEL NODE SERIALIZATION
+    // ========================================================================
+    // serializeContract, serializeFunction, serializeModule, serializeConstant,
+    // serializeVariableDecl, serializeStructDecl, serializeEnumDecl,
+    // serializeLogDecl, serializeImport, serializeErrorDecl, serializeBlock,
+    // serializeTryBlock
+    // ========================================================================
+
     fn serializeContract(self: *AstSerializer, contract: *const ast.ContractNode, writer: anytype, indent: u32, depth: u32) SerializationError!void {
         try self.writeField(writer, "type", "Contract", indent + 1, true);
         try self.writeField(writer, "name", contract.name, indent + 1, false);

src/ast/ast_visitor.zig

@@ -1,3 +1,24 @@
+// ============================================================================
+// AST Visitor
+// ============================================================================
+//
+// Generic visitor pattern for traversing AST nodes with flexible strategies.
+//
+// FEATURES:
+//   • Comptime-parameterized visitor with custom context
+//   • Optional visit callbacks for selective traversal
+//   • Depth-first and breadth-first strategies
+//   • Specialized visitors (symbol/type collecting)
+//   • Type-erased AnyVisitor wrapper
+//
+// USAGE:
+//   const MyCtx = struct { count: usize };
+//   var ctx = MyCtx{ .count = 0 };
+//   var visitor = Visitor(MyCtx, void){ .context = &ctx, .visitFunc = myFn };
+//   visitor.visit(&node);
+//
+// ============================================================================
+
 const std = @import("std");
 const ast = @import("../ast.zig");
 

src/ast/type_info.zig

@@ -1,3 +1,23 @@
+// ============================================================================
+// Type Information System
+// ============================================================================
+//
+// Unified type system providing comprehensive type representation,
+// validation, and operations for all AST nodes.
+//
+// KEY CONCEPTS:
+//   • TypeInfo: Unified type representation (category + ora_type + source)
+//   • TypeCategory: High-level classification (Integer, String, Array, etc.)
+//   • OraType: Specific type details (u8, u256, arrays, maps, 80+ variants)
+//   • TypeSource: How type was determined (explicit, inferred, unknown)
+//
+// SECTIONS:
+//   • TypeInfo core & common types
+//   • TypeCategory & OraType definitions
+//   • Type rendering & display
+//
+// ============================================================================
+
 const std = @import("std");
 const SourceSpan = @import("../ast.zig").SourceSpan;