chore(frontend): Elaborator module doc comments

compiler/noirc_frontend/src/elaborator/comptime.rs

@@ -1,3 +1,5 @@
+//! Comptime expression evaluation and macro expansion via the interpreter.
+
 use std::{collections::BTreeMap, fmt::Display};
 
 use iter_extended::vecmap;

compiler/noirc_frontend/src/elaborator/enums.rs

@@ -1,3 +1,5 @@
+//! Enum definition collection and variant resolution.
+
 use std::collections::{BTreeMap, BTreeSet};
 
 use iter_extended::{btree_map, try_vecmap, vecmap};

compiler/noirc_frontend/src/elaborator/expressions.rs

@@ -1,3 +1,5 @@
+//! Expression elaboration, covering all expression [kinds][ExpressionKind].
+
 use iter_extended::vecmap;
 use noirc_errors::{Located, Location};
 use rustc_hash::FxHashSet as HashSet;

compiler/noirc_frontend/src/elaborator/function_context.rs

@@ -1,3 +1,5 @@
+//! Function-local context management for type variables and trait constraints.
+
 use noirc_errors::Location;
 
 use crate::{

compiler/noirc_frontend/src/elaborator/generics.rs

@@ -1,3 +1,5 @@
+//! Generic parameter resolution and type parameter handling.
+
 use std::rc::Rc;
 
 use iter_extended::vecmap;

compiler/noirc_frontend/src/elaborator/globals.rs

@@ -1,3 +1,5 @@
+//! Global constant definition elaboration and comptime evaluation.
+
 use crate::{
     ast::{ExpressionKind, Literal, Pattern},
     hir::{def_collector::dc_crate::UnresolvedGlobal, resolution::errors::ResolverError},

compiler/noirc_frontend/src/elaborator/impls.rs

@@ -1,3 +1,5 @@
+//! Inherent type implementations collection and method declaration.
+
 use noirc_errors::Location;
 
 use crate::{

compiler/noirc_frontend/src/elaborator/lints.rs

@@ -1,3 +1,5 @@
+//! Lint checks for function attributes, visibility, and usage restrictions.
+
 use crate::{
     Type,
     ast::{Ident, NoirFunction},

compiler/noirc_frontend/src/elaborator/mod.rs

@@ -1,3 +1,53 @@
+//! # The Elaborator
+//!
+//! The elaborator is the core semantic analysis phase of the compiler. It transforms collected,
+//! unresolved AST items into fully resolved and type-checked HIR through simultaneous and intertwined
+//! name resolution, type checking, trait resolution, and macro expansion. It also handles pattern
+//! elaboration, generic type processing, comptime interpretation, reference validation, and scope management.
+//!
+//! ## Architecture Overview
+//!
+//! The elaborator operates in several distinct phases, processing items in a specific order to handle
+//! dependencies correctly:
+//!
+//! ### Early Resolution
+//! 1. Literal globals - Fully elaborated first since they may be used as numeric generics in struct definitions
+//! 2. Non-literal globals - Deferred for elaboration later after type resolution
+//! 3. Type aliases - Defined to allow their use in subsequent type definitions
+//!
+//! ### Type Collection
+//! 1. Struct definitions - Collected so their types are available for use
+//! 2. Enum definitions - Collected so their types are available for use
+//! 3. Trait definitions - Collected so trait bounds can be resolved
+//!
+//! ### Function metadata and Implementations
+//! 1. Function metadata - Signatures collected before bodies are elaborated
+//! 2. Trait methods - Method signatures collected from trait definitions
+//! 3. Impl blocks - Methods organized into their proper modules based on the impl's type
+//! 4. Trait impls - Linked to their corresponding traits and validated
+//!
+//! ### Non-literal Global Elaboration
+//! - Non-literal globals - Elaborated after type resolution since they may use struct types which need global type information
+//!
+//! ### Attribute Processing
+//! - Comptime attributes - Executed before function body elaboration, as generated items may change what is in scope or modify functions
+//!
+//! ### Full Item Elaboration
+//! 1. Functions - Function bodies elaborated (resolved & type-checked)
+//! 2. Traits - Trait default method implementations elaborated
+//! 3. Impls - Implementation method bodies elaborated
+//! 4. Trait impls - Trait implementation method bodies elaborated and validated against trait signatures
+//!
+//! ### Dependency Analysis
+//! Detect and report dependency cycles to prevent infinite elaboration loops
+//!
+//! ## Error Handling
+//!
+//! The elaborator accumulates errors rather than failing fast, allowing it to report multiple
+//! errors in a single compilation pass. Errors are collected throughout elaboration and may be
+//! wrapped with additional context when elaborating generated code (e.g., from attributes or
+//! comptime calls).
+
 use std::{
     cell::RefCell,
     collections::{BTreeMap, BTreeSet},

compiler/noirc_frontend/src/elaborator/options.rs

@@ -1,3 +1,5 @@
+//! Compiler frontend options and unstable feature flags.
+
 use std::str::FromStr;
 
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]

compiler/noirc_frontend/src/elaborator/path_resolution.rs

@@ -1,3 +1,5 @@
+//! Path resolution for types, values, and trait methods across modules.
+
 use iter_extended::vecmap;
 use noirc_errors::{Located, Location, Span};
 

compiler/noirc_frontend/src/elaborator/patterns.rs

@@ -1,3 +1,5 @@
+//! Pattern elaboration, variable binding, and turbofish generic resolution.
+
 use iter_extended::vecmap;
 use noirc_errors::{Located, Location};
 use rustc_hash::FxHashSet as HashSet;

compiler/noirc_frontend/src/elaborator/primitive_types.rs

@@ -1,3 +1,5 @@
+//! Primitive type definitions
+
 use noirc_errors::Location;
 
 use crate::{

compiler/noirc_frontend/src/elaborator/scope.rs

@@ -1,3 +1,5 @@
+//! Lexical scoping, variable lookup, and closure capture tracking.
+
 use crate::ast::{ERROR_IDENT, Ident};
 use crate::hir::def_map::{LocalModuleId, ModuleId};
 

compiler/noirc_frontend/src/elaborator/statements.rs

@@ -1,3 +1,5 @@
+//! Statement elaboration including let bindings, assignments, and control flow.
+
 use noirc_errors::Location;
 
 use crate::{

compiler/noirc_frontend/src/elaborator/structs.rs

@@ -1,3 +1,5 @@
+//! Struct definition collection and field resolution.
+
 use std::collections::BTreeMap;
 
 use iter_extended::vecmap;

compiler/noirc_frontend/src/elaborator/trait_impls.rs

@@ -1,3 +1,5 @@
+//! Trait implementation collection, method matching, and coherence checking.
+
 use crate::{
     Kind, NamedGeneric, ResolvedGeneric, Shared, TypeBindings, TypeVariable,
     ast::{Ident, UnresolvedType, UnresolvedTypeData, UnresolvedTypeExpression},

compiler/noirc_frontend/src/elaborator/traits.rs

@@ -1,3 +1,5 @@
+//! Trait definition collection, bounds resolution, and associated types.
+
 use std::{collections::BTreeMap, rc::Rc};
 
 use iter_extended::vecmap;

compiler/noirc_frontend/src/elaborator/types.rs

@@ -1,3 +1,5 @@
+//! Type resolution, unification, and method resolution (for both types and traits).
+
 use std::{borrow::Cow, rc::Rc};
 
 use im::HashSet;

compiler/noirc_frontend/src/elaborator/unquote.rs

@@ -1,3 +1,5 @@
+//! Token stream processing for macro unquoting and variable interpolation.
+
 use crate::{
     ast::Path,
     token::{Keyword, LocatedToken, Token, Tokens},

compiler/noirc_frontend/src/elaborator/visibility.rs

@@ -1,3 +1,5 @@
+//! Visibility checking for functions, struct fields, and type privacy.
+
 use noirc_errors::Location;
 
 use crate::{

compiler/noirc_frontend/src/hir_def/mod.rs

@@ -1,20 +1,10 @@
-//! Noir's Hir is the result of the name resolution step (defined in the
-//! hir module) and is essentially identical to the Ast with some small transformations.
-//! The HIR is the input to the name resolution pass, the type checking pass, and the
-//! monomorphization pass.
+//! Noir's HIR (High-Level Intermediate Representation) is produced by the elaboration pass
+//! and represents a fully resolved and type-checked program.
+//! The HIR is the input to the monomorphization pass.
 //!
-//! Name Resolution takes the AST as input and produces the initial Hir which strongly
-//! resembles the Ast except:
-//! - Variables now have DefinitionIDs that can be used to reference the definition that defines them.
-//! - Modules & imports are removed in favor of these direct links to definitions
-//! - Resolves names in UnresolvedTypes to produce resolved Types.
+//! Information about how the AST is transformed into an HIR can be found in the [elaborator][crate::elaborator] module.
 //!
-//! Type checking takes the Hir and:
-//! - Tags each DefinitionId with its type
-//! - Replaces MethodCall nodes with FunctionCalls
-//!
-//! Finally, monomorphization takes the Hir and converts it to a monomorphized Ir
-//! (monomorphization::ast::Expression).
+//! Monomorphization will take in the the HIR produced by elaboration and convert it to a monomorphized IR.
 pub mod expr;
 pub mod function;
 pub mod stmt;