chore: comment

evaluator/nixjit_error/src/lib.rs

@@ -1,17 +1,43 @@
+//! This crate defines the centralized error types and `Result` alias used
+//! throughout the entire `nixjit` evaluation pipeline. By consolidating error
+//! handling here, we ensure a consistent approach to reporting failures across
+//! different stages of processing, from parsing to final evaluation.
+
 use thiserror::Error;
 
+/// A specialized `Result` type used for all fallible operations within the
+/// `nixjit` crates. It defaults to the crate's `Error` type.
 pub type Result<T> = core::result::Result<T, Error>;
 
+/// The primary error enum, encompassing all potential failures that can occur
+/// during the lifecycle of a Nix expression's evaluation.
 #[derive(Error, Debug)]
 pub enum Error {
+    /// An error occurred during the initial parsing phase. This typically
+    /// indicates a syntax error in the Nix source code, as detected by the
+    /// `rnix` parser.
     #[error("error occurred during parse stage: {0}")]
     ParseError(String),
+
+    /// An error occurred while "downgrading" the `rnix` AST to the
+    /// High-Level IR (HIR). This can happen if the AST has a structure that is
+    /// syntactically valid but semantically incorrect for our IR.
     #[error("error occurred during downgrade stage: {0}")]
     DowngradeError(String),
+
+    /// An error occurred during the variable resolution phase, where the HIR is
+    /// converted to the Low-Level IR (LIR). This is most commonly caused by
+    /// an unbound or undefined variable.
     #[error("error occurred during variable resolve stage: {0}")]
     ResolutionError(String),
+
+    /// An error occurred during the final evaluation of the LIR. This covers
+    /// all runtime errors, such as type mismatches (e.g., adding a string to
+    /// an integer), division by zero, or failed `assert` statements.
     #[error("error occurred during evaluation stage: {0}")]
     EvalError(String),
-    #[error("unknown error")]
+
+    /// A catch-all for any error that does not fit into the other categories.
+    #[error("an unknown or unexpected error occurred")]
     Unknown,
 }