chore: comment

evaluator/nixjit_value/src/lib.rs

@@ -1,3 +1,9 @@
+//! Defines the public-facing data structures for Nix values.
+//!
+//! These types are used to represent the final result of an evaluation and are
+//! designed to be user-friendly and serializable. They are distinct from the
+//! internal `Value` types used during evaluation in `nixjit_eval`.
+
 use core::fmt::{Debug, Display, Formatter, Result as FmtResult};
 use core::hash::Hash;
 use core::ops::Deref;
@@ -9,8 +15,11 @@ use std::sync::LazyLock;
 use derive_more::{Constructor, IsVariant, Unwrap};
 use regex::Regex;
 
+/// Represents errors thrown by `assert` and `throw` expressions in Nix.
+/// These errors can potentially be caught and handled by `builtins.tryEval`.
 #[derive(Clone, Debug, PartialEq, Constructor, Hash)]
 pub struct Catchable {
+    /// The error message.
     msg: String,
 }
 
@@ -26,11 +35,16 @@ impl Display for Catchable {
     }
 }
 
+/// Represents a constant, primitive value in Nix.
 #[derive(Debug, Clone, Copy, PartialEq, IsVariant, Unwrap)]
 pub enum Const {
+    /// A boolean value (`true` or `false`).
     Bool(bool),
+    /// A 64-bit signed integer.
     Int(i64),
+    /// A 64-bit floating-point number.
     Float(f64),
+    /// The `null` value.
     Null,
 }
 
@@ -64,6 +78,7 @@ impl From<f64> for Const {
     }
 }
 
+/// Represents a Nix symbol, which is used as a key in attribute sets.
 #[derive(Debug, Clone, Hash, PartialEq, Eq, PartialOrd, Ord, Constructor)]
 pub struct Symbol(String);
 
@@ -73,9 +88,11 @@ impl<T: Into<String>> From<T> for Symbol {
     }
 }
 
-pub fn format_symbol<'a>(sym: &'a str) -> Cow<'a, str> {
-    if REGEX.is_match(sym) {
-        Cow::Borrowed(sym)
+/// Formats a string slice as a Nix symbol, quoting it if necessary.
+pub fn format_symbol<'a>(sym: impl Into<Cow<'a, str>>) -> Cow<'a, str> {
+    let sym = sym.into();
+    if REGEX.is_match(&sym) {
+        sym
     } else {
         Cow::Owned(format!(r#""{sym}""#))
     }
@@ -92,8 +109,9 @@ impl Display for Symbol {
 }
 
 static REGEX: LazyLock<Regex> =
-    LazyLock::new(|| Regex::new(r#"^[a-zA-Z\_][a-zA-Z0-9\_\'\-]*$"#).unwrap());
+    LazyLock::new(|| Regex::new(r"^[a-zA-Z_][a-zA-Z0-9_'-]*$").unwrap());
 impl Symbol {
+    /// Checks if the symbol is a "normal" identifier that doesn't require quotes.
     fn normal(&self) -> bool {
         REGEX.is_match(self)
     }
@@ -107,15 +125,18 @@ impl Deref for Symbol {
 }
 
 impl Symbol {
+    /// Consumes the `Symbol`, returning its inner `String`.
     pub fn into_inner(self) -> String {
         self.0
     }
 
+    /// Returns a reference to the inner `String`.
     pub fn as_inner(&self) -> &String {
         &self.0
     }
 }
 
+/// Represents a Nix attribute set, which is a map from symbols to values.
 #[derive(Constructor, Clone, PartialEq)]
 pub struct AttrSet {
     data: BTreeMap<Symbol, Value>,
@@ -124,15 +145,16 @@ pub struct AttrSet {
 impl Debug for AttrSet {
     fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult {
         use Value::*;
-        write!(f, "{{ ")?;
+        write!(f, "{{")?;
         for (k, v) in self.data.iter() {
+            write!(f, " {k:?} = ")?;
             match v {
-                List(_) => write!(f, "{k:?} = [ ... ]; ")?,
-                AttrSet(_) => write!(f, "{k:?} = {{ ... }}; ")?,
-                v => write!(f, "{k:?} = {v:?}; ")?,
+                List(_) => write!(f, "[ ... ];")?,
+                AttrSet(_) => write!(f, "{{ ... }};")?,
+                v => write!(f, "{v:?};")?,
             }
         }
-        write!(f, "}}")
+        write!(f, " }}")
     }
 }
 
@@ -140,19 +162,24 @@ impl Display for AttrSet {
     fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult {
         use Value::*;
         write!(f, "{{ ")?;
+        let mut first = true;
         for (k, v) in self.data.iter() {
+            if !first {
+                write!(f, "; ")?;
+            }
             write!(f, "{k} = ")?;
             match v {
                 AttrSet(_) => write!(f, "{{ ... }}"),
                 List(_) => write!(f, "[ ... ]"),
                 v => write!(f, "{v}"),
             }?;
-            write!(f, "; ")?;
+            first = false;
         }
-        write!(f, "}}")
+        write!(f, " }}")
     }
 }
 
+/// Represents a Nix list, which is a vector of values.
 #[derive(Constructor, Clone, Debug, PartialEq)]
 pub struct List {
     data: Vec<Value>,
@@ -168,17 +195,29 @@ impl Display for List {
     }
 }
 
+/// Represents any possible Nix value that can be returned from an evaluation.
 #[derive(IsVariant, Unwrap, Clone, Debug, PartialEq)]
 pub enum Value {
+    /// A constant value (int, float, bool, null).
     Const(Const),
+    /// A string value.
     String(String),
+    /// An attribute set.
     AttrSet(AttrSet),
+    /// A list.
     List(List),
+    /// A catchable error.
     Catchable(Catchable),
+    /// A thunk, representing a delayed computation.
     Thunk,
+    /// A function (lambda).
     Func,
+    /// A primitive (built-in) operation.
     PrimOp(&'static str),
+    /// A partially applied primitive operation.
     PrimOpApp(&'static str),
+    /// A marker for a value that has been seen before during serialization, to break cycles.
+    /// This is used to prevent infinite recursion when printing or serializing cyclic data structures.
     Repeated,
 }
 
@@ -187,7 +226,7 @@ impl Display for Value {
         use Value::*;
         match self {
             Const(x) => write!(f, "{x}"),
-            String(x) => write!(f, "{x}"),
+            String(x) => write!(f, r#""{x}""#),
             AttrSet(x) => write!(f, "{x}"),
             List(x) => write!(f, "{x}"),
             Catchable(x) => write!(f, "{x}"),